Skip to content

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

TypeScript
9.8 KB
Raw Blame
import {
  type McpServerOAuthReader,
  type McpServerOAuthSubject,
  type OAuthClientDecl,
  RecipeNotFoundError,
  type RecipeReader,
  type RecipeWithOAuthClients,
  SecretNotFoundError,
  type SecretReader,
} from './callback.js'
import { computeCodeChallengeS256, deriveCodeVerifier } from './pkce.js'
import {
  buildAdapterFromConfig,
  buildRemoteAuthorizeUrl,
  getOAuthProviderAdapter,
  isKnownOAuthProvider,
} from './providers.js'
import { type SignStateInput, signOAuthState } from './state.js'

/**
 * Build the provider authorize URL for an OAuth flow initiated on behalf of a
 * subject: a WorkflowRecipe (embed/admin Connect) or an OAuth McpServer (U5
 * reactive consent).
 *
 * The subject must declare the matching `oauthClientId` (recipe:
 * `spec.oauthClients[]`; mcp-server: `spec.oauth.id`). The subject is read from
 * K8s so we pick up the author-supplied scopes; the K8s Secret is read for the
 * real client_id (the provider needs it in the authorize URL).
 *
 * State is signed with the supplied secret and bound to the subject
 * (recipe: (ns, name, userId, oauthClientId); mcp: (mcpServerName, userId,
 * oauthClientId)) — the callback endpoint re-verifies this on the redirect.
 *
 * Spec §9.9 (recipe) · §U5 (mcp).
 */

interface BuildAuthorizeUrlCommonInput {
  oauthClientId: string
  /**
   * Authenticated user. For `grantKind: 'user'` this is the end-user the grant
   * will belong to (rpc-proxy decodes the session). For `grantKind: 'service'`
   * this is the initiating admin — recorded in the state for audit only. For an
   * mcp subject it is the initiating user (per-user grant owner, or shared-grant
   * bootstrapper resolved on the callback).
   */
  userId: string
  /**
   * [SEC-1] Which kind of grant this flow will mint. Required, non-defaulted:
   * the embed `/oauth/authorize-url` path MUST pass `'user'`, the admin connect
   * route passes `'service'`, the mcp path passes `'user'`. No fall-through.
   */
  grantKind: 'user' | 'service'
  /**
   * True when this flow captures background (offline) consent. Only ever true
   * on the embed background opt-in; the callback sets the grant's `background`
   * flag iff a refresh token is returned. Default false. (Never true for mcp.)
   */
  background?: boolean
  /** Public callback URL the provider will redirect to. */
  redirectUri: string
}

export type BuildAuthorizeUrlInput =
  | (BuildAuthorizeUrlCommonInput & {
      subjectKind?: 'recipe'
      recipeNamespace: string
      recipeName: string
    })
  | (BuildAuthorizeUrlCommonInput & {
      subjectKind: 'mcp'
      mcpServerName: string
    })

export interface BuildAuthorizeUrlDeps {
  recipeReader: RecipeReader
  /**
   * Resolver for OAuth McpServer subjects (U5). Required to build an mcp-subject
   * authorize URL; absent for pure recipe wiring.
   */
  mcpServerReader?: McpServerOAuthReader
  secretReader: SecretReader
  stateSecret: string
}

export type BuildAuthorizeUrlResult =
  | { kind: 'ok'; authorizeUrl: string }
  | { kind: 'recipe_not_found' }
  /** mcp subject: the McpServer named in the request does not exist / is not OAuth. */
  | { kind: 'server_not_found' }
  | { kind: 'unknown_oauth_client' }
  | { kind: 'background_access_not_enabled' }
  | { kind: 'unsupported_provider'; provider: string }
  | { kind: 'secret_missing'; secret: string }

export async function buildAuthorizeUrl(
  input: BuildAuthorizeUrlInput,
  deps: BuildAuthorizeUrlDeps
): Promise<BuildAuthorizeUrlResult> {
  if (input.subjectKind === 'mcp') {
    // ─── mcp subject (U5) ────────────────────────────────────────────────
    if (!deps.mcpServerReader) return { kind: 'server_not_found' }
    let subject: McpServerOAuthSubject | null
    try {
      subject = await deps.mcpServerReader.read(input.mcpServerName)
    } catch (err) {
      if (err instanceof RecipeNotFoundError) return { kind: 'server_not_found' }
      throw err
    }
    if (!subject) return { kind: 'server_not_found' }

    const decl = subject.decl
    if (decl.id !== input.oauthClientId) return { kind: 'unknown_oauth_client' }

    // The state binds the initiating user + the server; grant-scope routing is
    // resolved authoritatively on the callback, so the mcp state is per-user
    // shaped regardless of grantScope (context binding is authoritative via
    // spec.contextRef, not carried here).
    return mintAuthorizeUrl(decl, subject.namespace, input, deps, {
      subjectKind: 'mcp',
      mcpServerName: input.mcpServerName,
      userId: input.userId,
      oauthClientId: input.oauthClientId,
      grantKind: input.grantKind,
      background: input.background ?? false,
    })
  }

  // ─── recipe subject (unchanged) ──────────────────────────────────────────
  let recipe: RecipeWithOAuthClients | null
  try {
    recipe = await deps.recipeReader.read(input.recipeName, input.recipeNamespace)
  } catch (err) {
    if (err instanceof RecipeNotFoundError) return { kind: 'recipe_not_found' }
    throw err
  }
  if (!recipe) return { kind: 'recipe_not_found' }

  const decl = recipe.spec?.oauthClients?.find(c => c.id === input.oauthClientId)
  if (!decl) return { kind: 'unknown_oauth_client' }

  return mintAuthorizeUrl(decl, input.recipeNamespace, input, deps, {
    recipeNamespace: input.recipeNamespace,
    recipeName: input.recipeName,
    userId: input.userId,
    oauthClientId: input.oauthClientId,
    grantKind: input.grantKind,
    background: input.background ?? false,
  })
}

/**
 * Shared tail for both subjects: background gate, provider check, client_id
 * Secret read, state signing (subject-specific `stateInput`), PKCE challenge,
 * and the provider authorize URL. Signing is the ONLY subject-specific input —
 * the recipe `stateInput` reproduces the pre-U5 signed shape byte-for-byte.
 */
async function mintAuthorizeUrl(
  decl: OAuthClientDecl,
  secretNamespace: string,
  input: BuildAuthorizeUrlInput,
  deps: BuildAuthorizeUrlDeps,
  stateInput: SignStateInput
): Promise<BuildAuthorizeUrlResult> {
  // [SEC-4] A service grant, or any user flow requesting background (offline)
  // consent, may only be minted for a client whose author explicitly opted into
  // background access. Fail closed when the flag is absent. For the mcp path
  // (grantKind 'user', background false) this is a no-op.
  if (decl.backgroundAccess !== true && (input.grantKind === 'service' || input.background)) {
    return { kind: 'background_access_not_enabled' }
  }

  // Remote lane (`source:'remote'`): the authorize URL is built from the pinned
  // discovery-derived `authorizationEndpoint` with a PUBLIC client_id (`decl.id`,
  // backfilled for every mode — DEC-23), mandatory PKCE S256, and RFC 8707
  // `resource` unless the authorization-server profile omits it. No secret material
  // rides the URL and no K8s Secret is read.
  if (decl.remote) {
    const state = signOAuthState(deps.stateSecret, stateInput)
    const codeChallenge = computeCodeChallengeS256(deriveCodeVerifier(deps.stateSecret, state))
    const authorizeUrl = buildRemoteAuthorizeUrl(decl.remote.authorizationEndpoint, {
      clientId: decl.id,
      redirectUri: input.redirectUri,
      state,
      scopes: decl.scopes ?? [],
      codeChallenge,
      resource: decl.remote.resource,
    })
    return { kind: 'ok', authorizeUrl }
  }

  // Generic self-hosted lane (`source:'generic'`, DEC-28): the authorize URL is
  // composed from the pinned `authorizationEndpoint` + wire knobs
  // (`buildAdapterFromConfig`) with the PUBLIC client_id (`decl.id`). PKCE S256 is
  // gated on `usePkce`; when off, no challenge is computed or emitted. No K8s
  // Secret is read (the client_id rides `oauth.id`, not a Secret).
  if (decl.generic) {
    const state = signOAuthState(deps.stateSecret, stateInput)
    const codeChallenge = decl.generic.usePkce
      ? computeCodeChallengeS256(deriveCodeVerifier(deps.stateSecret, state))
      : undefined
    const authorizeUrl = buildAdapterFromConfig(decl.generic).buildAuthorizeUrl({
      clientId: decl.id,
      redirectUri: input.redirectUri,
      state,
      scopes: decl.scopes ?? [],
      codeChallenge,
    })
    return { kind: 'ok', authorizeUrl }
  }

  if (!isKnownOAuthProvider(decl.provider)) {
    return { kind: 'unsupported_provider', provider: decl.provider }
  }
  const adapter = getOAuthProviderAdapter(decl.provider)

  // Baked/recipe lane: clientIdRef is always present (only the remote lane, handled
  // above, 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}` }
  }

  const state = signOAuthState(deps.stateSecret, stateInput)

  // PKCE (DEC-1): derive the verifier deterministically from the signed state,
  // then send its S256 challenge. The callback re-derives the same verifier from
  // the round-tripped state — nothing PKCE-related is stored server-side.
  let codeChallenge: string | undefined
  if (adapter.usesPkce) {
    codeChallenge = computeCodeChallengeS256(deriveCodeVerifier(deps.stateSecret, state))
  }

  const authorizeUrl = adapter.buildAuthorizeUrl({
    clientId,
    redirectUri: input.redirectUri,
    state,
    scopes: decl.scopes ?? [],
    codeChallenge,
  })

  return { kind: 'ok', authorizeUrl }
}