Skip to content

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

TypeScript
6.9 KB
Raw Blame
import {
  CODEX_CONNECTION_REF_ANNOTATION,
  assertCodexConnectionKey,
  isCodexUnassignedConnectionKey,
} from './codexSubscriptionConnection.js'
import {
  assertGrokConnectionKey,
  isGrokUnassignedConnectionKey,
} from './grokSubscriptionConnection.js'
import {
  SUBSCRIPTION_CONNECTION_REF_ANNOTATION,
  collectRecipeOauthBrokerProviders,
} from './subscriptionGrantIdentity.js'

/**
 * Server authority for WorkflowRecipe oauth-broker grant annotations.
 *
 * Write shapes:
 *   - codex-subscription: `{codex-connection-ref: k, subscription-connection-ref: k}`
 *   - any other broker (grok-subscription): `{codex-connection-ref: '', subscription-connection-ref: k}`
 *
 * Transition table (explicit = either annotation key present in the body):
 *   - alias and canonical both non-empty and unequal → 422 on any spec
 *   - create / static→broker: omitted → grant required; explicit → validate, write shape
 *   - same broker: omitted → keep stored; explicit → validate, write shape
 *   - broker change: omitted → 422 providerChangeRequiresGrant; explicit → validate, write shape
 *   - broker→static: clear both unless the recipe declares pluginWorkloadSdk (SDK route owns it)
 *   - static→static / static create: keep (the SDK route owns static-recipe identity)
 *
 * Pure and total: every input maps to a result or 422 errors, never a throw.
 */

export interface RecipeGrantValidationError {
  field: string
  message: string
  rule?: string
}

export type RecipeGrantTransitionResult =
  | {
      ok: true
      /** Annotation patch merged over the stored annotations. `{}` keeps them. */
      annotations: Record<string, string>
    }
  | { ok: false; errors: RecipeGrantValidationError[] }

export interface RecipeGrantTransitionInput {
  body: {
    spec?: Record<string, unknown>
    metadata?: { annotations?: Record<string, unknown> }
  }
  /** Stored recipe on update; omitted for create and /validate. */
  current?: {
    spec?: Record<string, unknown>
    annotations?: Record<string, string>
  } | null
}

const ALIAS_FIELD = `metadata.annotations.${CODEX_CONNECTION_REF_ANNOTATION}`
const CANONICAL_FIELD = `metadata.annotations.${SUBSCRIPTION_CONNECTION_REF_ANNOTATION}`

type BrokerRules = {
  field: string
  requiredRule: string
  requiredMessage: string
  invalidRule: string
  invalidMessage: string
  isUnassigned: (key: string) => boolean
  assertKey: (key: string) => string
  shape: (key: string) => Record<string, string>
}

const CODEX_RULES: BrokerRules = {
  field: ALIAS_FIELD,
  requiredRule: 'codexRecipeGrantRequired',
  requiredMessage: 'Codex subscription recipes must choose an existing ChatGPT grant',
  invalidRule: 'codexRecipeGrantInvalid',
  invalidMessage: 'clerum.io/codex-connection-ref is not a valid connection key',
  isUnassigned: isCodexUnassignedConnectionKey,
  assertKey: assertCodexConnectionKey,
  shape: key => ({
    [CODEX_CONNECTION_REF_ANNOTATION]: key,
    [SUBSCRIPTION_CONNECTION_REF_ANNOTATION]: key,
  }),
}

const GROK_RULES: BrokerRules = {
  field: CANONICAL_FIELD,
  requiredRule: 'grokRecipeGrantRequired',
  requiredMessage: 'Grok subscription recipes must choose an existing Grok grant',
  invalidRule: 'grokRecipeGrantInvalid',
  invalidMessage: 'clerum.io/subscription-connection-ref is not a valid connection key',
  isUnassigned: isGrokUnassignedConnectionKey,
  assertKey: assertGrokConnectionKey,
  shape: key => ({
    [CODEX_CONNECTION_REF_ANNOTATION]: '',
    [SUBSCRIPTION_CONNECTION_REF_ANNOTATION]: key,
  }),
}

function brokerRules(provider: string): BrokerRules {
  return provider === 'codex-subscription' ? CODEX_RULES : GROK_RULES
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
}

function recipeBroker(spec: unknown): string | undefined {
  if (!isRecord(spec)) return undefined
  return collectRecipeOauthBrokerProviders(spec)[0]
}

function hasPluginWorkloadSdk(spec: unknown): boolean {
  return isRecord(spec) && isRecord(spec.pluginWorkloadSdk)
}

function stringAnnotation(annotations: Record<string, unknown>, key: string): string {
  const value = annotations[key]
  return typeof value === 'string' ? value.trim() : ''
}

function error(field: string, rule: string, message: string): RecipeGrantTransitionResult {
  return { ok: false, errors: [{ field, rule, message }] }
}

const CLEARED = {
  [CODEX_CONNECTION_REF_ANNOTATION]: '',
  [SUBSCRIPTION_CONNECTION_REF_ANNOTATION]: '',
}

export function resolveRecipeGrantTransition(
  input: RecipeGrantTransitionInput
): RecipeGrantTransitionResult {
  const rawAnnotations = isRecord(input.body.metadata?.annotations)
    ? input.body.metadata.annotations
    : {}
  const explicit =
    Object.prototype.hasOwnProperty.call(rawAnnotations, CODEX_CONNECTION_REF_ANNOTATION) ||
    Object.prototype.hasOwnProperty.call(rawAnnotations, SUBSCRIPTION_CONNECTION_REF_ANNOTATION)
  const alias = stringAnnotation(rawAnnotations, CODEX_CONNECTION_REF_ANNOTATION)
  const canonical = stringAnnotation(rawAnnotations, SUBSCRIPTION_CONNECTION_REF_ANNOTATION)
  const nextBroker = recipeBroker(input.body.spec)

  if (explicit && alias && canonical && alias !== canonical) {
    return error(
      nextBroker && nextBroker !== 'codex-subscription' ? CANONICAL_FIELD : ALIAS_FIELD,
      'subscriptionAnnotationsDisagree',
      'subscription connection annotations disagree'
    )
  }

  const current = input.current ?? undefined
  const previousBroker = current ? recipeBroker(current.spec) : undefined

  if (!nextBroker) {
    // Leaving a broker without an SDK: the agent grant no longer has an owner.
    if (previousBroker && !hasPluginWorkloadSdk(input.body.spec)) {
      return { ok: true, annotations: { ...CLEARED } }
    }
    // Static recipes (and SDK recipes leaving a broker) keep whatever the
    // plugin-workload-sdk grant route published.
    return { ok: true, annotations: {} }
  }

  const rules = brokerRules(nextBroker)
  if (!explicit) {
    if (previousBroker === nextBroker) return { ok: true, annotations: {} }
    if (previousBroker) {
      return error(
        rules.field,
        'providerChangeRequiresGrant',
        `Changing the recipe oauth-broker provider from ${previousBroker} to ${nextBroker} requires choosing a ${nextBroker} grant`
      )
    }
    return error(rules.field, rules.requiredRule, rules.requiredMessage)
  }

  let key: string
  if (nextBroker === 'codex-subscription') {
    key = canonical || alias
  } else {
    if (alias) {
      return error(
        CANONICAL_FIELD,
        'subscriptionAnnotationsDisagree',
        'Codex connection annotation is not valid for this oauth-broker provider'
      )
    }
    key = canonical
  }
  if (!key || rules.isUnassigned(key)) {
    return error(rules.field, rules.requiredRule, rules.requiredMessage)
  }
  try {
    rules.assertKey(key)
  } catch {
    return error(rules.field, rules.invalidRule, rules.invalidMessage)
  }
  return { ok: true, annotations: rules.shape(key) }
}