Skip to content

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

TypeScript
17.2 KB
Raw Blame
import type { K8sGateway } from '../../k8s.js'
import { rootLogger } from '../../observability/logger.js'
import { signWrcDelegationToken } from '../../utils/auth/delegationToken.js'
import { K8sNotFoundError } from '../resourceService.js'
import { getRun } from '../workflowRunService.js'
import type { WorkflowRunRow } from '../workflowRunService.js'
import type { WorkflowRouteCaller, WorkflowRunArtifactDto } from './types.js'
import type { WorkflowApprovalTarget } from './workflowRecipeAccessService.js'
import {
  WORKFLOW_RECIPE_PLURAL,
  asRecord,
  ensureRecipeAuthorized,
  isRecipeNamespaceAllowed,
} from './workflowRecipeAccessService.js'
import { canCallerReadWorkflowRunWithApprovalTarget } from './workflowRunReadService.js'
import { buildWrcWorkflowArtifactsUrl } from './wrcClient.js'

const WRC_ARTIFACT_FETCH_TIMEOUT_MS = 30_000
const SAFE_ARTIFACT_NAME_RE = /^[A-Za-z0-9._-]+$/
const WORKFLOW_RUN_ID_LABEL = 'clerum.io/workflow-run-id'
const logger = rootLogger.child({ module: 'workflow-run-artifacts' })

export class WorkflowArtifactHttpError extends Error {
  constructor(
    readonly status: number,
    message: string
  ) {
    super(message)
    this.name = 'WorkflowArtifactHttpError'
  }
}

export type WorkflowArtifactContext = {
  parentNamespace: string
  parentName: string
  run: WorkflowRunRow
  childRunId?: string
  childNamespace: string
  childName: string
  childRecipe: Record<string, unknown>
}

export type WorkflowArtifactDownloadResult = {
  status: number
  headers: Record<string, string>
  body: Buffer | Record<string, unknown>
}

export type WorkflowArtifactDeleteResult = {
  status: number
  body: Record<string, unknown>
}

export function isSafeWorkflowArtifactName(name: string): boolean {
  return SAFE_ARTIFACT_NAME_RE.test(name) && !name.includes('..')
}

function assertNever(value: never): never {
  throw new Error(`Unsupported workflow caller kind: ${JSON.stringify(value)}`)
}

function callerSubject(caller: WorkflowRouteCaller): string {
  switch (caller.kind) {
    case 'admin-ui':
      return `admin:${caller.userId}`
    case 'user-session':
      return `user:${caller.claims.userId}`
    case 'mcp-host-control':
      return `mcp-host:${caller.claims.sub}`
    default:
      return assertNever(caller)
  }
}

function callerUserId(caller: WorkflowRouteCaller): string {
  switch (caller.kind) {
    case 'admin-ui':
      return caller.userId
    case 'user-session':
      return caller.claims.userId
    case 'mcp-host-control':
      return caller.claims.sub
    default:
      return assertNever(caller)
  }
}

function extractErrorName(err: unknown): string {
  return err instanceof Error ? err.name : typeof err
}

function extractErrorMessage(err: unknown): string {
  return err instanceof Error ? err.message : String(err)
}

async function readResponseBodyWithLimit(
  response: Response,
  maxBytes: number | undefined
): Promise<Buffer> {
  if (maxBytes === undefined) {
    return Buffer.from(await response.arrayBuffer())
  }

  const contentLength = response.headers.get('content-length')
  if (contentLength && /^\d+$/.test(contentLength)) {
    const expectedBytes = Number(contentLength)
    if (!Number.isSafeInteger(expectedBytes) || expectedBytes > maxBytes) {
      throw new WorkflowArtifactHttpError(413, 'Artifact too large to download')
    }
  }

  if (!response.body) {
    const body = Buffer.from(await response.arrayBuffer())
    if (body.byteLength > maxBytes) {
      throw new WorkflowArtifactHttpError(413, 'Artifact too large to download')
    }
    return body
  }

  const reader = response.body.getReader()
  const chunks: Buffer[] = []
  let totalBytes = 0
  try {
    while (true) {
      const { done, value } = await reader.read()
      if (done) break
      const chunk = Buffer.from(value)
      totalBytes += chunk.byteLength
      if (totalBytes > maxBytes) {
        await reader.cancel().catch(() => undefined)
        throw new WorkflowArtifactHttpError(413, 'Artifact too large to download')
      }
      chunks.push(chunk)
    }
  } finally {
    reader.releaseLock()
  }
  return Buffer.concat(chunks, totalBytes)
}

function isTimeoutError(err: unknown): boolean {
  if (!(err instanceof Error)) return false
  return err.name === 'AbortError' || err.name === 'TimeoutError'
}

function isK8sNotFoundLike(err: unknown): boolean {
  if (err instanceof K8sNotFoundError) return true
  if (!err || typeof err !== 'object') return false
  const maybe = err as {
    name?: string
    statusCode?: number
    code?: number
    response?: { statusCode?: number; status?: number }
  }
  return (
    maybe.name === 'K8sNotFoundError' ||
    maybe.statusCode === 404 ||
    maybe.code === 404 ||
    maybe.response?.statusCode === 404 ||
    maybe.response?.status === 404
  )
}

function artifactDtoFromUnknown(value: unknown): WorkflowRunArtifactDto | null {
  const artifact = asRecord(value)
  if (!artifact) return null
  const name = typeof artifact.name === 'string' ? artifact.name.trim() : ''
  if (!name || !isSafeWorkflowArtifactName(name)) return null

  const format = typeof artifact.format === 'string' ? artifact.format.trim() : ''
  const rawSize = artifact.sizeBytes
  const sizeBytes = typeof rawSize === 'number' && Number.isSafeInteger(rawSize) ? rawSize : 0
  const createdAt =
    typeof artifact.createdAt === 'string' && artifact.createdAt.trim()
      ? artifact.createdAt
      : new Date(0).toISOString()

  return { name, format, sizeBytes: Math.max(0, sizeBytes), createdAt }
}

export function getWorkflowRunArtifactsFromRecipe(
  childRecipe: Record<string, unknown>
): WorkflowRunArtifactDto[] {
  const status = asRecord(childRecipe.status)
  const artifacts = status?.artifacts
  if (!Array.isArray(artifacts)) return []
  return artifacts
    .map(artifactDtoFromUnknown)
    .filter((artifact): artifact is WorkflowRunArtifactDto => artifact !== null)
}

function workflowRunIdFromChildRecipe(childRecipe: Record<string, unknown>): string | undefined {
  const metadata = asRecord(childRecipe.metadata)
  const labels = asRecord(metadata?.labels)
  const runId = labels?.[WORKFLOW_RUN_ID_LABEL]
  return typeof runId === 'string' && runId.trim() ? runId.trim() : undefined
}

export async function resolveWorkflowArtifactContext(params: {
  gateway: K8sGateway
  caller: WorkflowRouteCaller
  recipeNamespace: string
  recipeName: string
  runId: string
  approvalTarget?: WorkflowApprovalTarget
}): Promise<WorkflowArtifactContext> {
  const { gateway, caller, recipeNamespace, recipeName, runId, approvalTarget = {} } = params
  if (!isRecipeNamespaceAllowed(recipeNamespace)) {
    throw new WorkflowArtifactHttpError(404, `Recipe ${recipeNamespace}/${recipeName} not found`)
  }
  if (!(await ensureRecipeAuthorized(caller, recipeNamespace, recipeName, approvalTarget))) {
    logger.warn(
      {
        recipeNamespace,
        recipeName,
        callerKind: caller.kind,
        hasApprovalTarget: Boolean(approvalTarget?.targetUserId || approvalTarget?.targetTeamId),
      },
      'Workflow artifact access denied by recipe grant check'
    )
    throw new WorkflowArtifactHttpError(403, 'Not authorized to access artifacts for this recipe')
  }

  try {
    await gateway.getResource(WORKFLOW_RECIPE_PLURAL, recipeName, recipeNamespace)
  } catch (err) {
    if (isK8sNotFoundLike(err)) {
      throw new WorkflowArtifactHttpError(404, `Recipe ${recipeNamespace}/${recipeName} not found`)
    }
    throw err
  }

  const run = await getRun(runId)
  if (
    !run ||
    run.recipe_namespace !== recipeNamespace ||
    run.recipe_name !== recipeName ||
    !run.child_recipe_name ||
    !run.child_recipe_namespace
  ) {
    throw new WorkflowArtifactHttpError(
      404,
      `Run ${runId} not found for ${recipeNamespace}/${recipeName}`
    )
  }
  if (!(await canCallerReadWorkflowRunWithApprovalTarget(caller, run, approvalTarget))) {
    logger.warn(
      {
        runId,
        parentNamespace: recipeNamespace,
        parentName: recipeName,
        childNamespace: run.child_recipe_namespace,
        childName: run.child_recipe_name,
        approvalRequestId: run.approval_request_id,
        callerKind: caller.kind,
        hasApprovalTarget: Boolean(approvalTarget?.targetUserId || approvalTarget?.targetTeamId),
      },
      'Workflow artifact access denied by run ownership check'
    )
    throw new WorkflowArtifactHttpError(
      404,
      `Run ${runId} not found for ${recipeNamespace}/${recipeName}`
    )
  }
  if (!isRecipeNamespaceAllowed(run.child_recipe_namespace)) {
    logger.warn(
      {
        runId,
        parentNamespace: recipeNamespace,
        parentName: recipeName,
        childNamespace: run.child_recipe_namespace,
        childName: run.child_recipe_name,
      },
      'Workflow artifact child recipe namespace violated sandbox invariant'
    )
    throw new WorkflowArtifactHttpError(
      404,
      `Run ${runId} not found for ${recipeNamespace}/${recipeName}`
    )
  }

  let childRecipe: Record<string, unknown>
  try {
    const rawChildRecipe = await gateway.getResource(
      WORKFLOW_RECIPE_PLURAL,
      run.child_recipe_name,
      run.child_recipe_namespace
    )
    const childRecord = asRecord(rawChildRecipe)
    if (!childRecord) {
      logger.warn(
        {
          runId,
          parentNamespace: recipeNamespace,
          parentName: recipeName,
          childNamespace: run.child_recipe_namespace,
          childName: run.child_recipe_name,
        },
        'Workflow artifact child recipe response was malformed'
      )
      throw new WorkflowArtifactHttpError(502, 'Workflow run artifact metadata is malformed')
    }
    childRecipe = childRecord
  } catch (err) {
    if (err instanceof WorkflowArtifactHttpError) throw err
    if (isK8sNotFoundLike(err)) {
      logger.warn(
        {
          runId,
          parentNamespace: recipeNamespace,
          parentName: recipeName,
          childNamespace: run.child_recipe_namespace,
          childName: run.child_recipe_name,
        },
        'Workflow artifact child recipe was not found'
      )
      throw new WorkflowArtifactHttpError(410, 'Run artifact metadata has been pruned')
    }
    throw err
  }
  const childRunId = workflowRunIdFromChildRecipe(childRecipe)
  if (childRunId && childRunId !== run.run_id) {
    logger.warn(
      {
        runId,
        childRunId,
        parentNamespace: recipeNamespace,
        parentName: recipeName,
        childNamespace: run.child_recipe_namespace,
        childName: run.child_recipe_name,
      },
      'Workflow artifact child recipe run label did not match the requested run'
    )
    throw new WorkflowArtifactHttpError(
      404,
      `Run ${runId} not found for ${recipeNamespace}/${recipeName}`
    )
  }

  return {
    parentNamespace: recipeNamespace,
    parentName: recipeName,
    run,
    ...(childRunId ? { childRunId } : {}),
    childNamespace: run.child_recipe_namespace,
    childName: run.child_recipe_name,
    childRecipe,
  }
}

export async function listWorkflowRunArtifacts(params: {
  gateway: K8sGateway
  caller: WorkflowRouteCaller
  recipeNamespace: string
  recipeName: string
  runId: string
  approvalTarget?: WorkflowApprovalTarget
}): Promise<WorkflowRunArtifactDto[]> {
  const context = await resolveWorkflowArtifactContext(params)
  return getWorkflowRunArtifactsFromRecipe(context.childRecipe)
}

async function proxyWorkflowArtifactRequest(params: {
  context: WorkflowArtifactContext
  caller: WorkflowRouteCaller
  method: 'GET' | 'DELETE'
  artifactName?: string
}): Promise<Response> {
  const { context, caller, method, artifactName } = params
  if (method === 'DELETE' && caller.kind !== 'admin-ui') {
    throw new WorkflowArtifactHttpError(403, 'Only admin callers may delete workflow artifacts')
  }
  const delegationToken = signWrcDelegationToken({
    adminUserId: callerUserId(caller),
    subject: callerSubject(caller),
    recipeName: context.childName,
    recipeNamespace: context.childNamespace,
    ...(context.childRunId ? { runId: context.childRunId } : {}),
    ...(artifactName ? { artifactName } : {}),
    scope:
      caller.kind === 'admin-ui'
        ? method === 'GET'
          ? 'admin:artifact_read'
          : 'admin:artifact_delete'
        : 'artifact_read',
  })
  const wrcUrl = buildWrcWorkflowArtifactsUrl(context.childName, artifactName)

  try {
    return await fetch(wrcUrl, {
      method,
      headers: { authorization: `Bearer ${delegationToken}` },
      signal: AbortSignal.timeout(WRC_ARTIFACT_FETCH_TIMEOUT_MS),
    })
  } catch (err) {
    logger.error(
      {
        err: { name: extractErrorName(err), message: extractErrorMessage(err) },
        runId: context.run.run_id,
        parentNamespace: context.parentNamespace,
        parentName: context.parentName,
        childNamespace: context.childNamespace,
        childName: context.childName,
        artifactName,
      },
      method === 'GET' ? 'Workflow artifact fetch failed' : 'Workflow artifact delete failed'
    )
    throw new WorkflowArtifactHttpError(
      isTimeoutError(err) ? 504 : 502,
      isTimeoutError(err)
        ? 'Workflow artifact service timeout'
        : 'Workflow artifact service unreachable'
    )
  }
}

export async function downloadWorkflowRunArtifact(params: {
  gateway: K8sGateway
  caller: WorkflowRouteCaller
  recipeNamespace: string
  recipeName: string
  runId: string
  artifactName: string
  approvalTarget?: WorkflowApprovalTarget
  maxBytes?: number
}): Promise<WorkflowArtifactDownloadResult> {
  const { artifactName, caller, maxBytes } = params
  if (!artifactName || !isSafeWorkflowArtifactName(artifactName)) {
    throw new WorkflowArtifactHttpError(400, 'Invalid artifactName')
  }

  const context = await resolveWorkflowArtifactContext(params)
  const artifacts = getWorkflowRunArtifactsFromRecipe(context.childRecipe)
  if (!artifacts.some(artifact => artifact.name === artifactName)) {
    throw new WorkflowArtifactHttpError(
      404,
      `Artifact "${artifactName}" not found for run ${params.runId}`
    )
  }

  const upstream = await proxyWorkflowArtifactRequest({
    context,
    caller,
    method: 'GET',
    artifactName,
  })

  if (!upstream.ok) {
    let text = ''
    try {
      text = await upstream.text()
    } catch (err) {
      logger.warn(
        {
          err: { name: extractErrorName(err), message: extractErrorMessage(err) },
          status: upstream.status,
          runId: params.runId,
          childNamespace: context.childNamespace,
          childName: context.childName,
          artifactName,
        },
        'Failed to read workflow artifact upstream error body'
      )
    }
    logger.warn(
      {
        status: upstream.status,
        runId: params.runId,
        childNamespace: context.childNamespace,
        childName: context.childName,
        artifactName,
        bodyBytes: Buffer.byteLength(text, 'utf8'),
      },
      'Workflow artifact upstream returned non-OK response'
    )
    return {
      status: upstream.status,
      headers: { 'content-type': 'application/json' },
      body: { error: `Upstream returned ${upstream.status}` },
    }
  }

  const body = await readResponseBodyWithLimit(upstream, maxBytes)
  const upstreamDisposition = upstream.headers.get('content-disposition')
  const extractedName = upstreamDisposition?.match(/filename="?([^";\r\n]+)"?/)?.[1]
  const rawFilename =
    (extractedName ?? artifactName).replace(/\\/g, '/').split('/').pop() || artifactName
  const safeFilename = rawFilename.replace(/[^a-zA-Z0-9._-]/g, '_')

  return {
    status: 200,
    headers: {
      'content-type': upstream.headers.get('content-type') ?? 'application/octet-stream',
      'content-length': String(body.byteLength),
      'content-disposition': `attachment; filename="${safeFilename}"`,
    },
    body,
  }
}

export async function deleteWorkflowRunArtifact(params: {
  gateway: K8sGateway
  caller: WorkflowRouteCaller
  recipeNamespace: string
  recipeName: string
  runId: string
  artifactName: string
}): Promise<WorkflowArtifactDeleteResult> {
  const { artifactName, caller } = params
  if (!artifactName || !isSafeWorkflowArtifactName(artifactName)) {
    throw new WorkflowArtifactHttpError(400, 'Invalid artifactName')
  }

  const context = await resolveWorkflowArtifactContext(params)
  const artifacts = getWorkflowRunArtifactsFromRecipe(context.childRecipe)
  if (!artifacts.some(artifact => artifact.name === artifactName)) {
    throw new WorkflowArtifactHttpError(
      404,
      `Artifact "${artifactName}" not found for run ${params.runId}`
    )
  }

  const upstream = await proxyWorkflowArtifactRequest({
    context,
    caller,
    method: 'DELETE',
    artifactName,
  })

  if (!upstream.ok) {
    return {
      status: upstream.status,
      body: { error: `Upstream returned ${upstream.status}` },
    }
  }

  return { status: 204, body: {} }
}

export async function deleteWorkflowRunArtifacts(params: {
  gateway: K8sGateway
  caller: WorkflowRouteCaller
  recipeNamespace: string
  recipeName: string
  runId: string
}): Promise<WorkflowArtifactDeleteResult> {
  const context = await resolveWorkflowArtifactContext(params)
  const upstream = await proxyWorkflowArtifactRequest({
    context,
    caller: params.caller,
    method: 'DELETE',
  })

  if (!upstream.ok) {
    return {
      status: upstream.status,
      body: { error: `Upstream returned ${upstream.status}` },
    }
  }

  return { status: 204, body: {} }
}