Skip to content

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

TypeScript
10.8 KB
Raw Blame
import type { RegistryEntry } from './api'
import { readGenericImmutables } from './oauthGeneric'
import type { GenericConfigSuggestion, GenericImmutableView } from './oauthGeneric.types'
import type {
  CatalogOAuthBlock,
  McpSecretSummary,
  OAuthGrantScope,
  OAuthInstallSubmit,
  OAuthReferenceSecretInput,
} from './oauthInstall.types'
import { readRemoteImmutables } from './oauthRemote'
import type { RemoteImmutableView } from './oauthRemote.types'

// The public callback base URL for the exact redirect URI (D-B4) is a control-api
// server env (CONTROL_API_OAUTH_CALLBACK_BASE_URL). The wizard reads it at runtime
// from control-api (GET /admin/oauth/callback) as a template over this placeholder,
// never from a build-time NEXT_PUBLIC_* mirror. When control-api reports it unset the
// wizard refuses to invent a URI from window.location (a control-ui origin behind the
// funnel would guide the operator to register a broken redirect at the provider); it
// shows a "not configured" state instead, and control-api independently rejects the
// install with the same reason.
const OAUTH_CLIENT_ID_PLACEHOLDER = '{oauthClientId}'

const GRANT_SCOPES: ReadonlySet<string> = new Set<OAuthGrantScope>(['user', 'context'])

const GENERIC_STRING_KNOBS = [
  'authorizationEndpoint',
  'tokenEndpoint',
  'refreshEndpoint',
  'resource',
] as const
const GENERIC_ENUM_KNOBS: Record<string, readonly string[]> = {
  tokenRequestFormat: ['form', 'json'],
  tokenAuthMethod: ['body', 'basic'],
  scopeSeparator: ['space', 'comma'],
}
const GENERIC_BOOL_KNOBS = [
  'sendScope',
  'usePkce',
  'includeResponseType',
  'supportsRefresh',
] as const

/**
 * Defensively parse the catalog's `genericConfig` suggestion (E-19.6): keep only known
 * knob keys with the right primitive type; drop anything unexpected. Returns undefined
 * when nothing usable survives, so a malformed suggestion never reaches the wizard or
 * crashes the render (§9 risk 7). The catalog only SUGGESTS — control-api arbitrates.
 */
function parseGenericConfig(raw: unknown): GenericConfigSuggestion | undefined {
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return undefined
  const src = raw as Record<string, unknown>
  const out: GenericConfigSuggestion = {}

  for (const key of GENERIC_STRING_KNOBS) {
    const v = src[key]
    if (typeof v === 'string' && v.length > 0) out[key] = v
  }
  for (const [key, allowed] of Object.entries(GENERIC_ENUM_KNOBS)) {
    const v = src[key]
    if (typeof v === 'string' && allowed.includes(v)) {
      ;(out as Record<string, unknown>)[key] = v
    }
  }
  for (const key of GENERIC_BOOL_KNOBS) {
    const v = src[key]
    if (typeof v === 'boolean') out[key] = v
  }
  const extra = src.extraAuthorizeParams
  if (extra && typeof extra === 'object' && !Array.isArray(extra)) {
    const record: Record<string, string> = {}
    for (const [k, v] of Object.entries(extra as Record<string, unknown>)) {
      if (typeof v === 'string') record[k] = v
    }
    if (Object.keys(record).length > 0) out.extraAuthorizeParams = record
  }

  return Object.keys(out).length > 0 ? out : undefined
}

/**
 * Preview mirror of control-api's `deriveOAuthClientId` (routes/admin/registry.ts).
 * The operator NEVER types `oauth.id`; control-api derives and validates it at
 * install (D-B5). This mirror only renders the read-only preview so the operator
 * can see the callback coordinate before submitting — control-api stays the
 * single authority, so a drift here is a cosmetic preview bug, not a wrong write.
 */
export function deriveOAuthClientIdPreview(serverName: string): string {
  return serverName
    .toLowerCase()
    .replace(/[^a-z0-9-]/g, '-')
    .replace(/-+/g, '-')
    .replace(/^-+/, '')
    .slice(0, 63)
    .replace(/-+$/, '')
}

/**
 * The exact redirect URI the operator registers at the provider (D-B4), filled from
 * control-api's `redirectUriTemplate` (GET /admin/oauth/callback), which control-api
 * renders with the same builder its install/authorize path uses. Returns null when
 * there is no usable template (not configured) or the id is empty — the caller shows
 * a notice rather than a broken URI.
 */
export function buildOAuthRedirectUri(
  template: string | undefined,
  oauthId: string
): string | null {
  const trimmed = (template ?? '').trim()
  if (!trimmed.includes(OAUTH_CLIENT_ID_PLACEHOLDER) || !oauthId) return null
  return trimmed.replace(OAUTH_CLIENT_ID_PLACEHOLDER, encodeURIComponent(oauthId))
}

/**
 * Extracts and shallow-validates the frozen `mcp_server_meta.oauth` block. Returns
 * null when the entry declares no OAuth (the caller then uses the ordinary
 * connector install). Only fields the wizard understands survive. For a
 * `provider:'generic'` entry the catalog's `genericConfig` suggestion is parsed
 * defensively and kept (E-19.6); the wizard seeds from it, the admin confirms, and
 * control-api arbitrates (S-4).
 */
export function getCatalogOAuthBlock(
  entry: RegistryEntry | null | undefined
): CatalogOAuthBlock | null {
  const raw = entry?.mcp_server_meta?.oauth
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
  const block = raw as Record<string, unknown>
  if (typeof block.provider !== 'string' || block.provider.trim().length === 0) return null

  const result: CatalogOAuthBlock = { provider: block.provider }
  if (typeof block.grantScope === 'string' && GRANT_SCOPES.has(block.grantScope)) {
    result.grantScope = block.grantScope as OAuthGrantScope
  }
  if (Array.isArray(block.scopes)) {
    result.scopes = block.scopes.filter((s): s is string => typeof s === 'string')
  }
  const genericConfig = parseGenericConfig(block.genericConfig)
  if (genericConfig) result.genericConfig = genericConfig
  return result
}

/**
 * Parses the free-text scopes field into a clean, de-duplicated list. Operators
 * paste scopes separated by whitespace, newlines, or commas; all are normalised.
 */
export function parseScopesInput(text: string): string[] {
  const seen = new Set<string>()
  const out: string[] = []
  for (const token of text.split(/[\s,]+/)) {
    const scope = token.trim()
    if (scope && !seen.has(scope)) {
      seen.add(scope)
      out.push(scope)
    }
  }
  return out
}

/** Renders a scope list back into the editable textarea (one per line). */
export function formatScopesForInput(scopes: readonly string[]): string {
  return scopes.join('\n')
}

/**
 * GAP-6 UI gate: a baked OAuth server must never be submitted with an empty scope
 * list. The wizard blocks submit until the operator has at least one scope,
 * mirroring the server's reject (control-api computes an effective scope list and
 * rejects `[]`).
 */
export function scopesAreSatisfied(scopes: readonly string[]): boolean {
  return scopes.length > 0
}

// The OAuth fields that are CEL-immutable on the mcpserver CRD (D-B7): a change
// means delete + recreate, so the edit form shows them read-only. `scopes` is
// deliberately absent — it is editable (D-B6). `generic` is present only for the
// `source:'generic'` carril and `remote` only for `source:'remote'`: each carril's
// endpoints and wire knobs are create-only (GENERIC-IMM / IMM-6) and shown read-only
// alongside the base fields.
export type OAuthImmutableFields = {
  id: string
  provider: string
  grantScope: OAuthGrantScope | ''
  generic?: GenericImmutableView
  remote?: RemoteImmutableView
}

/**
 * Reads the immutable OAuth fields off an installed McpServer's `spec.oauth` for a
 * read-only display in the edit form (D-B7). Returns null when the server carries
 * no OAuth block. A generic connector has no `provider` (it is discriminated by
 * `source:'generic'`, DEC-28); it is surfaced with a synthetic `provider:'generic'`
 * label plus its read-only endpoints/knobs. A remote connector likewise carries no
 * `provider` (REMOTE-FORBID-PROVIDER) and is discriminated by `source:'remote'`; it is
 * surfaced with a synthetic `provider:'remote'` label plus its read-only remote fields.
 */
export function extractOAuthImmutables(
  spec: Record<string, unknown> | null | undefined
): OAuthImmutableFields | null {
  const raw = spec?.oauth
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
  const oauth = raw as Record<string, unknown>
  const grantScope =
    oauth.grantScope === 'user' || oauth.grantScope === 'context' ? oauth.grantScope : ''
  const id = typeof oauth.id === 'string' ? oauth.id : ''

  if (oauth.source === 'generic') {
    return {
      id,
      provider: 'generic',
      grantScope,
      generic: readGenericImmutables(oauth),
    }
  }

  if (oauth.source === 'remote') {
    return {
      id,
      provider: 'remote',
      grantScope,
      remote: readRemoteImmutables(oauth),
    }
  }

  const provider = typeof oauth.provider === 'string' ? oauth.provider : ''
  if (!provider) return null
  return { id, provider, grantScope }
}

/**
 * The name of the Secret that holds this OAuth connector's client credential
 * (D-B7 edit view). It is `spec.oauth.clientSecretRef.name` (falling back to
 * `clientIdRef.name` when the pair shares one Secret) — for a managed install
 * this is `${serverName}-oauth-client`, for a referenced install it is whatever
 * the operator named. Returns null when no ref is present.
 */
export function oauthClientSecretRefName(
  spec: Record<string, unknown> | null | undefined
): string | null {
  const raw = spec?.oauth
  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
  const oauth = raw as Record<string, unknown>
  for (const key of ['clientSecretRef', 'clientIdRef']) {
    const ref = oauth[key]
    if (
      ref &&
      typeof ref === 'object' &&
      typeof (ref as Record<string, unknown>).name === 'string'
    ) {
      return (ref as { name: string }).name
    }
  }
  return null
}

/**
 * Reference-mode pre-check (Fam. B(1)): the Secret must exist and carry both named
 * keys BEFORE submit, so the wizard never writes a CR whose refs dangle. Returns a
 * human message when something is missing, else null. `GET /admin/mcp-secrets`
 * returns names + keys only (never values), so this is safe to run client-side.
 */
export function referenceSecretIssue(
  ref: Pick<OAuthReferenceSecretInput, 'secretName' | 'clientIdKey' | 'clientSecretKey'>,
  secrets: readonly McpSecretSummary[]
): string | null {
  const secretName = ref.secretName.trim()
  const clientIdKey = ref.clientIdKey.trim()
  const clientSecretKey = ref.clientSecretKey.trim()
  if (!secretName) return 'Choose an existing Secret.'
  if (!clientIdKey || !clientSecretKey) return 'Name the Client ID key and the Client Secret key.'

  const match = secrets.find(secret => secret.name === secretName)
  if (!match) return `Secret "${secretName}" was not found in the MCP servers namespace.`

  const keySet = new Set(match.keys)
  const missing = [clientIdKey, clientSecretKey].filter(key => !keySet.has(key))
  if (missing.length > 0) {
    return `Secret "${secretName}" is missing key(s): ${missing.join(', ')}.`
  }
  return null
}