Skip to content

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

TypeScript
41.7 KB
Raw Blame
import { MAX_EGRESS_BINDINGS } from './egressModel'
import type {
  OperatorDefaults,
  ValidationIssue,
  ValidationResult,
  WorkflowRecipeResource,
  WorkloadType,
} from './recipeTypes'
import { ALLOWED_WORKLOAD_TYPES } from './recipeTypes'

// RFC1123 DNS label: lowercase alphanumeric + hyphens, start/end alphanumeric, 1-63 chars
const RFC1123_RE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/
const SECRET_KEY_RE = /^[-._a-zA-Z0-9]+$/
export const WORKFLOW_RECIPE_UI_LIMITS = {
  maxSteps: 100,
  stepDependsOnMaxItems: 100,
  stepAllowedToolsMaxItems: 50,
  stepMcpServersMaxItems: 20,
} as const
export const DEFAULT_STEP_OUTPUT_PREVIEW_MAX_CHARS = 32 * 1024
export const KUBERNETES_OBJECT_BUDGET_BYTES = 1.5 * 1024 * 1024

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

const STEP_RUN_KEYS = new Set(['type', 'language', 'code', 'capabilities'])
const SENSITIVE_ENV_NAME_RE = /(PASSWORD|TOKEN|SECRET|API_KEY|CREDENTIAL|PRIVATE_KEY)/i
const TEMPLATE_INPUT_REF_RE = /\{\{\s*inputs\.([A-Za-z0-9_.-]+)\s*\}\}/g
const SENSITIVE_INPUT_NAME_RE =
  /(password|passwd|pwd|token|secret|credential|api[_-]?key|apikey|private[_-]?key|privatekey)/i
const JWT_LIKE_RE = /^[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}$/
const SECRET_LIKE_VALUE_RE = /^(sk-[A-Za-z0-9_-]{8,}|pat[A-Za-z0-9_-]{8,})$/
const URL_WITH_PASSWORD_RE = /^[a-z][a-z0-9+.-]*:\/\/[^/\s:@]+:([^@\s]+)@/i
const INPUT_TEMPLATE_ONLY_RE = /^\{\{\s*inputs\.[A-Za-z0-9_.-]+\s*\}\}$/

function validateWorkflowSecretName(name: unknown): string | null {
  if (typeof name !== 'string' || !RFC1123_RE.test(name)) {
    return 'secretRef.name must be a lowercase RFC1123 label (letters, digits, hyphens; max 63 chars)'
  }
  if (name.startsWith('wf-')) {
    return `Secret "${name}" is platform-managed and cannot be used by WorkflowRecipe configuration.`
  }
  return null
}

function validateWorkflowSecretKey(key: unknown): string | null {
  if (typeof key !== 'string' || key.length === 0 || !SECRET_KEY_RE.test(key)) {
    return 'secret key must contain only letters, digits, dot, dash, or underscore'
  }
  return null
}

function sensitiveInputRefsInEnvValue(value: unknown): string[] {
  if (typeof value !== 'string' || !value.includes('{{')) return []

  const refs = new Set<string>()
  for (const match of value.matchAll(TEMPLATE_INPUT_REF_RE)) {
    const inputName = match[1]
    if (SENSITIVE_INPUT_NAME_RE.test(inputName)) {
      refs.add(`{{inputs.${inputName}}}`)
    }
  }
  return [...refs]
}

function parsePvcSizeGi(size: string): number {
  const m = size.match(/^(\d+(?:\.\d+)?)(Gi|Mi|G|M|Ti|T)$/)
  if (!m) return 0
  const num = parseFloat(m[1])
  const unit = m[2]
  if (unit === 'Ti' || unit === 'T') return num * 1024
  if (unit === 'Mi' || unit === 'M') return num / 1024
  return num // Gi or G
}

function inlineEnvSecretReason(name: unknown, value: unknown): string | null {
  const envName = typeof name === 'string' ? name.trim() : ''
  if (value === undefined || value === null || value === '') return null
  const envValue = typeof value === 'string' ? value.trim() : String(value)
  const urlPassword = envValue.match(URL_WITH_PASSWORD_RE)?.[1]
  const hasSensitiveInputTemplate = sensitiveInputRefsInEnvValue(envValue).length > 0
  if (
    JWT_LIKE_RE.test(envValue) ||
    SECRET_LIKE_VALUE_RE.test(envValue) ||
    (urlPassword !== undefined && !INPUT_TEMPLATE_ONLY_RE.test(urlPassword)) ||
    envValue.includes('-----BEGIN ')
  ) {
    return 'env value looks sensitive'
  }
  if (SENSITIVE_ENV_NAME_RE.test(envName) && !hasSensitiveInputTemplate) {
    return 'env name looks sensitive'
  }
  return null
}

/**
 * 3-phase client-side validation for WorkflowRecipe JSON.
 *
 * Phase 1 — Parse: JSON.parse the raw string.
 * Phase 2 — Schema: apiVersion, kind, metadata.name, workloads structure.
 * Phase 3 — Security: runAsUser >= 1, capabilities allowlist, PVC size limits.
 *
 * Returns `valid: false` if any error-severity issue exists.
 */
export function validateRecipe(input: string, defaults?: OperatorDefaults): ValidationResult {
  const issues: ValidationIssue[] = []

  // ── Phase 1: JSON Parse ──────────────────────────────────────────────────
  let parsed: WorkflowRecipeResource
  try {
    parsed = JSON.parse(input) as WorkflowRecipeResource
    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
      issues.push({
        phase: 'parse',
        severity: 'error',
        path: '',
        message: 'Root value must be a JSON object',
      })
      return { valid: false, issues }
    }
  } catch (e) {
    issues.push({
      phase: 'parse',
      severity: 'error',
      path: '',
      message: `Invalid JSON: ${e instanceof Error ? e.message : String(e)}`,
    })
    return { valid: false, issues }
  }

  // ── Phase 2: Schema ──────────────────────────────────────────────────────
  if (parsed.apiVersion !== 'clerum.io/v1alpha1') {
    issues.push({
      phase: 'schema',
      severity: 'error',
      path: 'apiVersion',
      message: 'Must be "clerum.io/v1alpha1"',
    })
  }

  if (parsed.kind !== 'WorkflowRecipe') {
    issues.push({
      phase: 'schema',
      severity: 'error',
      path: 'kind',
      message: 'Must be "WorkflowRecipe"',
    })
  }

  const name = parsed.metadata?.name ?? ''
  if (!name) {
    issues.push({
      phase: 'schema',
      severity: 'error',
      path: 'metadata.name',
      message: 'name is required',
    })
  } else if (!RFC1123_RE.test(name)) {
    issues.push({
      phase: 'schema',
      severity: 'error',
      path: 'metadata.name',
      message:
        'Must match RFC1123 (lowercase alphanumeric and hyphens, 1-63 chars, start/end alphanumeric). Example: "my-recipe"',
    })
  }

  // Namespace is intentionally not validated from recipe YAML. The platform
  // always stores WorkflowRecipe CRDs in `sandbox-recipes`; control-api strips
  // any author-supplied metadata.namespace before create/update. Rendered
  // workload placement is still split by the WRC reconciler:
  //   MCP workloads (with transport) -> mcp-server
  //   non-MCP workloads / PVCs       -> sandbox-recipes

  const steps = parsed.spec?.steps
  const isWorkflow = Array.isArray(steps) && steps.length > 0
  const hasCustomCoordinator =
    typeof (parsed.spec as Record<string, unknown> | undefined)?.coordinatorImage === 'string' &&
    ((parsed.spec as Record<string, unknown>).coordinatorImage as string).trim() !== ''

  // ── Validate steps[] (agentic / snippet workflows) ─────────────────
  if (isWorkflow) {
    if (steps!.length > WORKFLOW_RECIPE_UI_LIMITS.maxSteps) {
      issues.push({
        phase: 'schema',
        severity: 'error',
        path: 'spec.steps',
        message: `Must contain at most ${WORKFLOW_RECIPE_UI_LIMITS.maxSteps} items`,
      })
    }
    const projectedStatusPreviewBytes = steps!.length * DEFAULT_STEP_OUTPUT_PREVIEW_MAX_CHARS
    if (projectedStatusPreviewBytes >= KUBERNETES_OBJECT_BUDGET_BYTES) {
      issues.push({
        phase: 'schema',
        severity: 'warning',
        path: 'spec.steps',
        message:
          `This recipe can store up to ${(projectedStatusPreviewBytes / 1024 / 1024).toFixed(1)}MiB ` +
          `of bounded step output previews in WorkflowRecipe CRD status with the default ` +
          `WRC_WORKFLOW_STEP_OUTPUT_PREVIEW_MAX_CHARS=${DEFAULT_STEP_OUTPUT_PREVIEW_MAX_CHARS}. ` +
          `This does not limit full run files: complete intermediate and final outputs should be written to /output artifacts on workflow storage and retained by the workflow retention policy. ` +
          `For large or complex workflows, declare explicit PVC-backed output/storage with an appropriate size instead of using status output as storage. ` +
          `Keep only status previews under the Kubernetes object budget.`,
      })
    }

    const stepIds = new Set<string>()
    const duplicateStepIds = new Set<string>()
    steps!.forEach((s, i) => {
      const prefix = `spec.steps[${i}]`
      if (!s.id) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `${prefix}.id`,
          message: 'id is required',
        })
      } else if (stepIds.has(s.id)) {
        if (!duplicateStepIds.has(s.id)) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: `${prefix}.id`,
            message: `Duplicate step id "${s.id}"`,
          })
          duplicateStepIds.add(s.id)
        }
      } else {
        stepIds.add(s.id)
      }
      const stepObj = s as Record<string, unknown>
      const hasInstruction = stepObj.instruction !== undefined
      const hasRun = stepObj.run !== undefined
      const stepDependsOn = stepObj.dependsOn
      if (
        Array.isArray(stepDependsOn) &&
        stepDependsOn.length > WORKFLOW_RECIPE_UI_LIMITS.stepDependsOnMaxItems
      ) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `${prefix}.dependsOn`,
          message: `Must contain at most ${WORKFLOW_RECIPE_UI_LIMITS.stepDependsOnMaxItems} items`,
        })
      }
      const stepMcpServers = stepObj.mcpServers
      if (
        Array.isArray(stepMcpServers) &&
        stepMcpServers.length > WORKFLOW_RECIPE_UI_LIMITS.stepMcpServersMaxItems
      ) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `${prefix}.mcpServers`,
          message: `Must contain at most ${WORKFLOW_RECIPE_UI_LIMITS.stepMcpServersMaxItems} items`,
        })
      }

      if (hasInstruction && hasRun) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: prefix,
          message: 'Step cannot declare both instruction and run',
        })
      } else if (!hasCustomCoordinator && hasInstruction === hasRun) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: prefix,
          message: 'Step must declare exactly one of instruction or run',
        })
      }
      if (
        hasInstruction &&
        (typeof stepObj.instruction !== 'string' || stepObj.instruction.trim() === '')
      ) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `${prefix}.instruction`,
          message: 'instruction must be a non-empty plain string',
        })
      }
      if (hasRun) {
        const run = stepObj.run
        if (!isPlainObject(run)) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: `${prefix}.run`,
            message: 'run must be an object',
          })
        } else {
          for (const key of Object.keys(run)) {
            if (!STEP_RUN_KEYS.has(key)) {
              issues.push({
                phase: 'schema',
                severity: 'error',
                path: `${prefix}.run.${key}`,
                message: 'unsupported run field',
              })
            }
          }
          if (run.type !== 'snippet') {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.run.type`,
              message: 'run.type must be "snippet"',
            })
          }
          if (run.language !== 'typescript') {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.run.language`,
              message: 'snippet language must be typescript',
            })
          }
          if (typeof run.code !== 'string' || run.code.trim() === '') {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.run.code`,
              message: 'snippet code must be a non-empty string',
            })
          }
          if (run.capabilities !== undefined && !isPlainObject(run.capabilities)) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.run.capabilities`,
              message: 'snippet capabilities must be an object',
            })
          } else if (isPlainObject(run.capabilities) && Array.isArray(run.capabilities.secrets)) {
            run.capabilities.secrets.forEach((entry, j) => {
              if (!isPlainObject(entry)) return
              const secretRef = isPlainObject(entry.secretRef) ? entry.secretRef : undefined
              if (!secretRef) return
              const secretNameError = validateWorkflowSecretName(secretRef.name)
              if (secretNameError) {
                issues.push({
                  phase: 'security',
                  severity: 'error',
                  path: `${prefix}.run.capabilities.secrets[${j}].secretRef.name`,
                  message: secretNameError,
                })
              }
              const secretKeyError = validateWorkflowSecretKey(secretRef.key)
              if (secretKeyError) {
                issues.push({
                  phase: 'security',
                  severity: 'error',
                  path: `${prefix}.run.capabilities.secrets[${j}].secretRef.key`,
                  message: secretKeyError,
                })
              }
            })
          }
        }
      }
      if (stepObj.maxIterations !== undefined) {
        const mi = Number(stepObj.maxIterations)
        if (!Number.isInteger(mi) || mi < 1 || mi > 100) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: `${prefix}.maxIterations`,
            message: 'Must be an integer between 1 and 100',
          })
        }
      }

      // requiresApproval validation
      const ra = stepObj.requiresApproval as Record<string, unknown> | undefined
      if (ra !== undefined) {
        if (typeof ra !== 'object' || ra === null || Array.isArray(ra)) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: `${prefix}.requiresApproval`,
            message: 'Must be an object',
          })
        } else {
          const target = ra.target as Record<string, unknown> | undefined
          const userId = typeof target?.userId === 'string' ? target.userId.trim() : ''
          const teamId = typeof target?.teamId === 'string' ? target.teamId.trim() : ''
          if (!target || (!userId && !teamId)) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.requiresApproval.target`,
              message: 'target.userId or target.teamId is required',
            })
          } else if (userId && teamId) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.requiresApproval.target`,
              message: 'Only one of target.userId or target.teamId may be set',
            })
          }
          const message = typeof ra.message === 'string' ? ra.message : ''
          if (!message.trim()) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.requiresApproval.message`,
              message: 'message is required',
            })
          } else if (message.length > 2000) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.requiresApproval.message`,
              message: 'message must be 2000 characters or fewer',
            })
          }
          if (ra.timeoutSeconds !== undefined) {
            const ts = Number(ra.timeoutSeconds)
            if (!Number.isInteger(ts) || ts < 30 || ts > 604800) {
              issues.push({
                phase: 'schema',
                severity: 'error',
                path: `${prefix}.requiresApproval.timeoutSeconds`,
                message: 'Must be an integer between 30 and 604800',
              })
            }
          }
        }
      }
    })
    steps!.forEach((s, i) => {
      ;(s.dependsOn ?? []).forEach((ref, j) => {
        if (!stepIds.has(ref)) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: `spec.steps[${i}].dependsOn[${j}]`,
            message: `References unknown step id "${ref}"`,
          })
        }
      })
    })
  }

  // ── Validate spec.triggers ──────────────────────────────────────────────
  const triggers = (parsed.spec as Record<string, unknown> | undefined)?.triggers as
    | Record<string, unknown>
    | undefined
  if (isWorkflow && triggers === undefined) {
    issues.push({
      phase: 'schema',
      severity: 'error',
      path: 'spec.triggers',
      message:
        'Workflow recipes with steps must declare spec.triggers.onDemand or spec.triggers.schedule',
    })
  }
  if (triggers !== undefined) {
    if (!isPlainObject(triggers)) {
      issues.push({
        phase: 'schema',
        severity: 'error',
        path: 'spec.triggers',
        message: 'Must be an object',
      })
    } else {
      const onDemand = triggers.onDemand as Record<string, unknown> | undefined
      const schedule = triggers.schedule as Record<string, unknown> | undefined
      if (!onDemand && !schedule) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: 'spec.triggers',
          message: 'Must declare at least one of onDemand or schedule',
        })
      }
      if (onDemand && isPlainObject(onDemand)) {
        const actors = onDemand.allowedActors
        if (Array.isArray(actors)) {
          const valid = new Set(['user', 'autonomous', 'scheduled'])
          actors.forEach((a, j) => {
            if (!valid.has(a as string)) {
              issues.push({
                phase: 'schema',
                severity: 'error',
                path: `spec.triggers.onDemand.allowedActors[${j}]`,
                message: `Must be one of: user, autonomous, scheduled`,
              })
            }
          })
        }
      }
      if (schedule && isPlainObject(schedule)) {
        const cron = typeof schedule.cron === 'string' ? schedule.cron.trim() : ''
        if (!cron) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: 'spec.triggers.schedule.cron',
            message: 'cron is required',
          })
        } else if (!/^(\S+\s+){4}\S+$/.test(cron)) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: 'spec.triggers.schedule.cron',
            message: 'Must be a valid five-field cron expression (e.g. "0 */6 * * *")',
          })
        }
        const cp = schedule.concurrencyPolicy
        if (cp !== undefined && !['Forbid', 'Replace', 'Allow'].includes(cp as string)) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: 'spec.triggers.schedule.concurrencyPolicy',
            message: 'Must be one of: Forbid, Replace, Allow',
          })
        }
      }
    }
    if (triggers && !isWorkflow) {
      issues.push({
        phase: 'schema',
        severity: 'error',
        path: 'spec.triggers',
        message: 'triggers requires spec.steps to be non-empty',
      })
    }
  }

  // ── Validate spec.runRetention ────────────────────────────────────────
  const runRetention = (parsed.spec as Record<string, unknown> | undefined)?.runRetention as
    | Record<string, unknown>
    | undefined
  if (runRetention !== undefined && isPlainObject(runRetention)) {
    const shl = runRetention.successfulHistoryLimit
    if (shl !== undefined) {
      const n = Number(shl)
      if (!Number.isInteger(n) || n < 0 || n > 50) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: 'spec.runRetention.successfulHistoryLimit',
          message: 'Must be an integer between 0 and 50',
        })
      }
    }
    const fhl = runRetention.failedHistoryLimit
    if (fhl !== undefined) {
      const n = Number(fhl)
      if (!Number.isInteger(n) || n < 0 || n > 100) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: 'spec.runRetention.failedHistoryLimit',
          message: 'Must be an integer between 0 and 100',
        })
      }
    }
    const ttl = runRetention.ttlSecondsAfterFinished
    if (ttl !== undefined) {
      const n = Number(ttl)
      if (!Number.isInteger(n) || n < 0 || n > 2_592_000) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: 'spec.runRetention.ttlSecondsAfterFinished',
          message: 'Must be an integer between 0 and 2592000 (30 days)',
        })
      }
    }
    const maxRunDuration = runRetention.maxRunDurationSeconds
    if (maxRunDuration !== undefined) {
      const n = Number(maxRunDuration)
      if (!Number.isInteger(n) || n < 1) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: 'spec.runRetention.maxRunDurationSeconds',
          message: 'Must be a positive integer',
        })
      }
    }
  }

  // ── Validate output.destination enum ────────────────────────────────────
  const outputDest = (parsed.spec as Record<string, unknown> | undefined)?.output as
    | Record<string, unknown>
    | undefined
  if (outputDest?.destination !== undefined) {
    const allowed = ['configmap', 'secret', 'stdout', 'pvc']
    if (!allowed.includes(outputDest.destination as string)) {
      issues.push({
        phase: 'schema',
        severity: 'error',
        path: 'spec.output.destination',
        message: `Unsupported value "${String(outputDest.destination)}" — must be one of: ${allowed.join(', ')}`,
      })
    }
  }

  // ── Validate mcpServers[] ────────────────────────────────────────────────
  // endpoint is auto-computed by WRC for workloads with transport — only required
  // for external connectors that don't have a matching workload.
  const mcpServers = parsed.spec?.mcpServers
  const transportWorkloadIds = new Set(
    (parsed.spec?.workloads ?? [])
      .filter(w => w.transport)
      .map(w => w.id)
      .filter(Boolean)
  )
  if (Array.isArray(mcpServers) && mcpServers.length > 0) {
    mcpServers.forEach((m, i) => {
      const prefix = `spec.mcpServers[${i}]`
      if (!m.id) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `${prefix}.id`,
          message: 'id is required',
        })
      } else if (!m.endpoint && !transportWorkloadIds.has(m.id)) {
        // endpoint required only if there's no MCP workload in the recipe that
        // already provides the server identity via the current transport-backed path
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `${prefix}.endpoint`,
          message:
            'endpoint is required for external connectors (not backed by an MCP workload declared in workloads[])',
        })
      }
    })
  }

  // ── Cross-validate: step mcpServer refs → workload IDs ────────────────────
  if (isWorkflow) {
    const mcpServerIds = Array.isArray(mcpServers) ? mcpServers.map(m => m.id).filter(Boolean) : []
    const validMcpIds = new Set(mcpServerIds)
    transportWorkloadIds.forEach(id => validMcpIds.add(id))
    ;(steps ?? []).forEach((s, i) => {
      const stepObj = s as Record<string, unknown>
      const stepMcpRefs = (stepObj.mcpServers as string[]) ?? []
      stepMcpRefs.forEach((ref, j) => {
        if (!validMcpIds.has(ref)) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: `spec.steps[${i}].mcpServers[${j}]`,
            message: `References unknown connector "${ref}" — must match an MCP workload id in workloads[] or an mcpServers[].id entry`,
          })
        }
      })
      // Validate allowedTools: tool names must use serverName__toolName prefix
      // and the serverName must be one of the step's declared mcpServers —
      // EXCEPT for built-in prefixes (currently "clerum") which StepMcpRouter
      // registers automatically before MCP connect (see CLAUDE.md "Internal
      // Output Tools"). Built-ins do NOT need to appear in mcpServers.
      const BUILTIN_TOOL_PREFIXES = new Set(['clerum'])
      const allowed = (stepObj.allowedTools as { include?: string[] } | undefined)?.include
      if (Array.isArray(allowed) && allowed.length > 0) {
        if (allowed.length > WORKFLOW_RECIPE_UI_LIMITS.stepAllowedToolsMaxItems) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: `spec.steps[${i}].allowedTools.include`,
            message: `Must contain at most ${WORKFLOW_RECIPE_UI_LIMITS.stepAllowedToolsMaxItems} items`,
          })
        }
        const stepServerSet = new Set(stepMcpRefs)
        allowed.forEach((toolName, j) => {
          if (!toolName.includes('__')) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `spec.steps[${i}].allowedTools.include[${j}]`,
              message: `Tool "${toolName}" must use serverName__toolName format (e.g. "web-search__search")`,
            })
          } else {
            const serverPrefix = toolName.split('__')[0]
            if (BUILTIN_TOOL_PREFIXES.has(serverPrefix)) {
              // built-in — no validation needed
              return
            }
            if (!stepServerSet.has(serverPrefix)) {
              issues.push({
                phase: 'schema',
                severity: 'warning',
                path: `spec.steps[${i}].allowedTools.include[${j}]`,
                message: `Tool "${toolName}" references server "${serverPrefix}" not listed in this step's mcpServers`,
              })
            }
          }
        })
      }
    })
  }

  const workloads = parsed.spec?.workloads
  if (!Array.isArray(workloads) || workloads.length === 0) {
    if (!isWorkflow) {
      issues.push({
        phase: 'schema',
        severity: 'error',
        path: 'spec.workloads',
        message: 'Must be a non-empty array',
      })
    }
  }
  // ── contextRef is OPTIONAL when workloads have transport ─────────────────
  //
  // When the recipe omits `spec.contextRef`, the WRC reconciler
  // (`mcpDelegation.ts::ensureRecipeContext`) auto-creates a per-recipe
  // Context named `wf-<recipeName>` with owner-reference to the recipe.
  // That private Context lists ONLY the recipe's connectors — no sharing
  // with first-party aggregated contexts like "context1".
  //
  // Historically this rule required contextRef as an error, which pushed
  // authors toward shared contexts by default (e.g. "context1"). The
  // auto-context is the secure default: private, garbage-collected with
  // the recipe, no cross-recipe first-party server exposure. An explicit
  // contextRef is only needed when the author WANTS to share servers
  // across recipes.
  //
  // We leave an INFO-level hint so authors who are new to the platform
  // understand what happens when they omit the field.
  const hasTransportWorkload = Array.isArray(workloads) && workloads.some(w => w.transport)
  if (hasTransportWorkload && !parsed.spec?.contextRef) {
    issues.push({
      phase: 'schema',
      severity: 'info',
      path: 'spec.contextRef',
      message:
        'Omitted — WRC will auto-create a private connector scope for this recipe. Set explicitly only to share connectors with other recipes in the same namespace.',
    })
  }

  if (Array.isArray(workloads) && workloads.length > 0) {
    const seenIds = new Set<string>()

    workloads.forEach((w, i) => {
      const prefix = `spec.workloads[${i}]`
      const workloadObject = w as Record<string, unknown>

      if (!w.id) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `${prefix}.id`,
          message: 'id is required',
        })
      } else if (seenIds.has(w.id)) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `${prefix}.id`,
          message: `Duplicate workload id "${w.id}"`,
        })
      } else {
        seenIds.add(w.id)
      }

      if (!w.type) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `${prefix}.type`,
          message: 'type is required',
        })
      } else if (!ALLOWED_WORKLOAD_TYPES.includes(w.type as WorkloadType)) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `${prefix}.type`,
          message: `Must be one of: ${ALLOWED_WORKLOAD_TYPES.join(', ')}`,
        })
      }

      if (!w.image) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `${prefix}.image`,
          message: 'image is required',
        })
      }

      const env = workloadObject.env
      if (Array.isArray(env)) {
        env.forEach((entry, j) => {
          if (!isPlainObject(entry)) return
          const reason = inlineEnvSecretReason(entry.name, entry.value)
          if (reason) {
            issues.push({
              phase: 'security',
              severity: 'error',
              path: `${prefix}.env[${j}].value`,
              message: `${reason}; move this value to envSecret`,
            })
          }
          const sensitiveInputRefs = sensitiveInputRefsInEnvValue(entry.value)
          if (sensitiveInputRefs.length > 0) {
            issues.push({
              phase: 'security',
              severity: 'warning',
              path: `${prefix}.env[${j}].value`,
              message:
                `env.value references sensitive input template(s) ${sensitiveInputRefs.join(', ')}; ` +
                'prefer envSecret or secretRef instead of storing secrets in spec.inputs',
            })
          }
        })
      }

      const envSecret = workloadObject.envSecret
      if (isPlainObject(envSecret)) {
        const secretNameError = validateWorkflowSecretName(envSecret.name)
        if (secretNameError) {
          issues.push({
            phase: 'security',
            severity: 'error',
            path: `${prefix}.envSecret.name`,
            message: secretNameError,
          })
        }
        if (Array.isArray(envSecret.keys)) {
          envSecret.keys.forEach((entry, j) => {
            if (!isPlainObject(entry)) return
            const secretKeyError = validateWorkflowSecretKey(entry.secretKey)
            if (secretKeyError) {
              issues.push({
                phase: 'security',
                severity: 'error',
                path: `${prefix}.envSecret.keys[${j}].secretKey`,
                message: secretKeyError,
              })
            }
          })
        }
      }

      const egressBindings = workloadObject.egressBindings
      if (Array.isArray(egressBindings)) {
        if (egressBindings.length > MAX_EGRESS_BINDINGS) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: `${prefix}.egressBindings`,
            message: `egressBindings must contain at most ${MAX_EGRESS_BINDINGS} items`,
          })
        }
        egressBindings.forEach((binding, j) => {
          const bindingPath = `${prefix}.egressBindings[${j}]`
          if (!isPlainObject(binding)) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: bindingPath,
              message: 'Must be an object',
            })
            return
          }

          const egressClass = binding.egressClass ?? 'exact-host'
          if (egressClass !== 'exact-host' && egressClass !== 'public-web') {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${bindingPath}.egressClass`,
              message: 'egressClass must be exact-host or public-web',
            })
          }

          if (Object.prototype.hasOwnProperty.call(binding, 'cidr')) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${bindingPath}.cidr`,
              message: 'cidr is not allowed on WorkflowRecipe egressBindings',
            })
          }

          const allowedKeys = new Set(['egressClass', 'dns', 'port', 'protocol'])
          for (const key of Object.keys(binding)) {
            if (!allowedKeys.has(key)) {
              issues.push({
                phase: 'schema',
                severity: 'error',
                path: `${bindingPath}.${key}`,
                message: `"${key}" is not allowed on WorkflowRecipe egressBindings`,
              })
            }
          }

          if (egressClass === 'public-web') {
            const hasExactHostFields =
              Object.prototype.hasOwnProperty.call(binding, 'dns') ||
              Object.prototype.hasOwnProperty.call(binding, 'port') ||
              Object.prototype.hasOwnProperty.call(binding, 'protocol')
            if (hasExactHostFields) {
              issues.push({
                phase: 'schema',
                severity: 'error',
                path: bindingPath,
                message: 'public-web egressBindings must not declare dns, port, or protocol',
              })
            }
            if (!workloadObject.transport) {
              issues.push({
                phase: 'schema',
                severity: 'error',
                path: `${bindingPath}.egressClass`,
                message:
                  'public-web is only supported on MCP transport workloads; non-transport workloads must use exact-host egressBindings',
              })
            } else if (!hasExactHostFields) {
              issues.push({
                phase: 'security',
                severity: 'warning',
                path: `${bindingPath}.egressClass`,
                message:
                  'public-web allows public internet egress on TCP 80/443 with private, metadata, service, and reserved ranges blocked by NetworkPolicy',
              })
            }
            return
          }

          const port = binding.port
          if (typeof port !== 'number' || !Number.isInteger(port) || port < 1 || port > 65535) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${bindingPath}.port`,
              message: 'port must be an integer between 1 and 65535',
            })
          }

          const dns = typeof binding.dns === 'string' ? binding.dns.trim() : ''
          if (!dns) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${bindingPath}.dns`,
              message: 'dns is required',
            })
          } else {
            if (dns.includes('/')) {
              issues.push({
                phase: 'schema',
                severity: 'error',
                path: `${bindingPath}.dns`,
                message: 'dns must not use CIDR notation',
              })
            }
            if (dns === '*' || dns.startsWith('*.')) {
              issues.push({
                phase: 'schema',
                severity: 'error',
                path: `${bindingPath}.dns`,
                message: 'wildcard dns values are not allowed',
              })
            }
          }
        })
      }
    })

    const runtimeEgress = (parsed.spec as Record<string, unknown> | undefined)?.runtimeEgress
    if (isPlainObject(runtimeEgress) && isPlainObject(runtimeEgress.http)) {
      const allowedHosts = runtimeEgress.http.allowedHosts
      if (Array.isArray(allowedHosts) && allowedHosts.length > MAX_EGRESS_BINDINGS) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: 'spec.runtimeEgress.http.allowedHosts',
          message: `allowedHosts must contain at most ${MAX_EGRESS_BINDINGS} items`,
        })
      }
    }

    const stepArray = Array.isArray(steps) ? (steps as Array<Record<string, unknown>>) : []
    stepArray.forEach((step, i) => {
      const run = isPlainObject(step.run) ? step.run : undefined
      const capabilities = isPlainObject(run?.capabilities) ? run.capabilities : undefined
      const http = isPlainObject(capabilities?.http) ? capabilities.http : undefined
      const allowedHosts = http?.allowedHosts
      if (Array.isArray(allowedHosts) && allowedHosts.length > MAX_EGRESS_BINDINGS) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: `spec.steps[${i}].run.capabilities.http.allowedHosts`,
          message: `allowedHosts must contain at most ${MAX_EGRESS_BINDINGS} items`,
        })
      }
    })

    // Validate dependsOn cross-references (after building seenIds)
    workloads.forEach((w, i) => {
      ;(w.dependsOn ?? []).forEach((ref, j) => {
        if (!seenIds.has(ref)) {
          issues.push({
            phase: 'schema',
            severity: 'error',
            path: `spec.workloads[${i}].dependsOn[${j}]`,
            message: `References unknown workload id "${ref}"`,
          })
        }
      })
    })

    const transportIds = new Set(
      workloads
        .filter(w => Boolean(w.transport))
        .map(w => w.id)
        .filter(Boolean)
    )
    const bindings = (parsed.spec as Record<string, unknown> | undefined)?.bindings
    if (bindings !== undefined) {
      if (!Array.isArray(bindings)) {
        issues.push({
          phase: 'schema',
          severity: 'error',
          path: 'spec.bindings',
          message: 'bindings must be an array',
        })
      } else {
        bindings.forEach((binding, i) => {
          const prefix = `spec.bindings[${i}]`
          if (!isPlainObject(binding)) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: prefix,
              message: 'Must be an object',
            })
            return
          }

          const from = typeof binding.from === 'string' ? binding.from.trim() : ''
          const to = typeof binding.to === 'string' ? binding.to.trim() : ''
          if (!from) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.from`,
              message: 'from is required',
            })
          } else if (!seenIds.has(from)) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.from`,
              message: `References unknown workload id "${from}"`,
            })
          }
          if (!to) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.to`,
              message: 'to is required',
            })
          } else if (!seenIds.has(to)) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.to`,
              message: `References unknown workload id "${to}"`,
            })
          }

          const port = Number(binding.port)
          if (!Number.isInteger(port) || port < 1 || port > 65535) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.port`,
              message: 'port must be an integer between 1 and 65535',
            })
          }
          if (
            binding.protocol !== undefined &&
            !['TCP', 'UDP'].includes(String(binding.protocol))
          ) {
            issues.push({
              phase: 'schema',
              severity: 'error',
              path: `${prefix}.protocol`,
              message: 'protocol must be one of: TCP, UDP',
            })
          }

          if (from && to && seenIds.has(from) && seenIds.has(to)) {
            const transportEndpoints = [from, to].filter(id => transportIds.has(id))
            if (transportEndpoints.length !== 1) {
              issues.push({
                phase: 'schema',
                severity: 'error',
                path: prefix,
                message:
                  'binding must connect exactly one MCP transport workload to one non-transport workload',
              })
            }
          }
        })
      }
    }
  }

  // ── Phase 3: Security Compliance ────────────────────────────────────────
  if (defaults && Array.isArray(workloads)) {
    workloads.forEach((w, i) => {
      const prefix = `spec.workloads[${i}]`
      const sec = w.security

      if (sec) {
        if (sec.runAsUser !== undefined && sec.runAsUser < 1) {
          issues.push({
            phase: 'security',
            severity: 'error',
            path: `${prefix}.security.runAsUser`,
            message: 'Must be >= 1 (UID 0 / root is rejected by policy)',
          })
        }

        ;(sec.addCapabilities ?? []).forEach((cap, j) => {
          if (!defaults.security.allowedCapabilities.includes(cap)) {
            issues.push({
              phase: 'security',
              severity: 'error',
              path: `${prefix}.security.addCapabilities[${j}]`,
              message: `"${cap}" is not in the operator's allowed capabilities list (${defaults.security.allowedCapabilities.join(', ')})`,
            })
          }
        })
      }

      ;(w.volumeClaimTemplates ?? []).forEach((vct, j) => {
        const sizeGi = parsePvcSizeGi(vct.size ?? '0')
        if (sizeGi > defaults.storage.maxPvcSizeGi) {
          issues.push({
            phase: 'security',
            severity: 'warning',
            path: `${prefix}.volumeClaimTemplates[${j}].size`,
            message: `${vct.size} exceeds operator max PVC size (${defaults.storage.maxPvcSizeGi}Gi)`,
          })
        }
      })
    })
  }

  const valid = !issues.some(issue => issue.severity === 'error')
  return { valid, issues, parsed }
}