Skip to content

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

TypeScript
10.5 KB
Raw Blame
import { createHash } from 'node:crypto'
import {
  type FileReferenceV1,
  buildAttachmentFileReference,
  classifyBytes,
} from '@clerum/gfs-interaction-policy'
import { FileAttachmentErrorCode } from '../core/errors'
import type { Attachment } from '../core/types'
import {
  type ImageAttachmentMimeType,
  isCanonicalBase64Shape,
  isImageAttachmentMime,
} from '../llm/imageInput'
import type { TaskError } from '../queue/types'

/**
 * Attachments (images and files together) accepted in one incoming message.
 * Kept separate from `CLERUM_ATTACHMENT_MAX_COUNT`, which caps the attachments
 * a response returns.
 * Must match COMPOSER_MAX_ATTACHMENTS in desktop-app/ui/src/constants/attachments.ts.
 * Per-image bytes stay on the channel `attachmentMaxBytes` (issue #654 / PR
 * #669) — this module must not clamp general inbound traffic to the Codex
 * `VISUAL_LIMITS`. The Codex chat hop is a separate 24 MiB parser with a
 * credited budget of 16 MiB of decoded image bytes and another of 16 MiB of
 * file base64 (about 12 MiB decoded). Per-file bytes use
 * `attachmentFileMaxBytes` (issue #666, 11 MiB by default per issue #678).
 * This count is the fail-loud admission cap.
 */
export const INCOMING_ATTACHMENT_MAX_COUNT = 20

/**
 * Longest media type a file attachment may declare. RFC 6838 caps a type/subtype
 * pair at 127 + 1 + 127 characters; the declaration reaches the persisted
 * message and the turn context, so it is bounded like the file name.
 */
export const FILE_ATTACHMENT_MIME_TYPE_MAX_LENGTH = 255

export type IncomingAttachmentValidation =
  | { ok: true; attachments: Attachment[] | undefined; fileReferences: FileReferenceV1[] }
  | { ok: false; error: TaskError }

export interface IncomingAttachmentLimits {
  maxCount: number
  /** Decoded bytes per `kind:'image'` attachment. */
  maxBytes: number
  /** Decoded bytes per `kind:'file'` attachment. */
  maxFileBytes: number
  /** The message the attachments arrived with; part of each file reference id. */
  messageId: string
}

/**
 * First bytes every accepted encoding must start with. The declared media type
 * decides how the provider serializes the image, so a declaration the bytes
 * contradict is rejected here rather than forwarded upstream (CWE-345).
 */
const MIME_SIGNATURES: Readonly<Record<ImageAttachmentMimeType, Buffer>> = {
  'image/png': Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
  'image/jpeg': Buffer.from([0xff, 0xd8, 0xff]),
}

const SHA256_HEX = /^[0-9a-f]{64}$/

function bytesMatchDeclaredMime(bytes: Buffer, mimeType: ImageAttachmentMimeType): boolean {
  const signature = MIME_SIGNATURES[mimeType]
  return bytes.length >= signature.length && bytes.subarray(0, signature.length).equals(signature)
}

type ItemResult = { ok: true; attachment: Attachment } | { ok: false; error: TaskError }

function taskError(code: string, message: string): { ok: false; error: TaskError } {
  return { ok: false, error: { code, message, retryable: false, provider: 'unknown' } }
}

const rejectImage = (message: string) => taskError('LLM_INVALID_ATTACHMENT', message)

// The image branch is the #669 contract, unchanged: same checks, same order,
// same code and messages.
function validateImage(item: Record<string, unknown>, maxBytes: number): ItemResult {
  if (
    !isImageAttachmentMime(item.mimeType) ||
    item.encoding !== 'base64' ||
    typeof item.dataBase64 !== 'string' ||
    typeof item.id !== 'string' ||
    !item.id.trim()
  ) {
    return rejectImage('Only PNG or JPEG images encoded as base64 are supported.')
  }
  const data = item.dataBase64
  // Check length before decoding so validation cannot allocate an oversized
  // binary buffer. Canonical base64 avoids ambiguous/partially decoded input.
  if (data.length > Math.ceil(maxBytes / 3) * 4)
    return rejectImage('An image exceeds the attachment size limit.')
  if (!isCanonicalBase64Shape(data)) {
    return rejectImage('An image has invalid base64 data. Attach the original file again.')
  }
  const bytes = Buffer.from(data, 'base64')
  if (bytes.length > maxBytes) return rejectImage('An image exceeds the attachment size limit.')
  if (bytes.toString('base64') !== data)
    return rejectImage('An image has invalid base64 data. Attach the original file again.')
  if (!bytesMatchDeclaredMime(bytes, item.mimeType))
    return rejectImage('An image does not match its declared type. Attach the original file again.')
  return {
    ok: true,
    attachment: {
      id: item.id,
      kind: 'image',
      mimeType: item.mimeType,
      encoding: 'base64',
      dataBase64: data,
      ...(typeof item.filename === 'string' ? { filename: item.filename } : {}),
      ...(typeof item.width === 'number' && Number.isFinite(item.width) && item.width > 0
        ? { width: item.width }
        : {}),
      ...(typeof item.height === 'number' && Number.isFinite(item.height) && item.height > 0
        ? { height: item.height }
        : {}),
    },
  }
}

const rejectFile = (message: string) => taskError(FileAttachmentErrorCode.Invalid, message)

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

/**
 * Any file type is admitted (D14). Only an invalid shape, an oversized file or
 * a digest the bytes contradict is rejected; the class and reader are derived
 * from the whole file and never from the caller's declaration.
 */
function validateFile(item: Record<string, unknown>, limits: IncomingAttachmentLimits): ItemResult {
  const digest = item.digest
  if (
    typeof item.id !== 'string' ||
    !item.id.trim() ||
    typeof item.filename !== 'string' ||
    typeof item.mimeType !== 'string' ||
    typeof item.detectedMediaType !== 'string' ||
    item.encoding !== 'base64' ||
    typeof item.dataBase64 !== 'string' ||
    typeof item.sizeBytes !== 'number' ||
    !Number.isSafeInteger(item.sizeBytes) ||
    item.sizeBytes < 0 ||
    !isPlainRecord(digest) ||
    digest.algorithm !== 'sha256' ||
    typeof digest.hex !== 'string' ||
    !SHA256_HEX.test(digest.hex)
  ) {
    return rejectFile('A file attachment is malformed. Attach the original file again.')
  }
  if (item.mimeType.length > FILE_ATTACHMENT_MIME_TYPE_MAX_LENGTH)
    return rejectFile('A file attachment declares a media type that is too long.')
  const data = item.dataBase64
  const tooLarge = taskError(
    FileAttachmentErrorCode.TooLarge,
    'A file exceeds the attachment size limit.'
  )
  // Same pre-decode bound as the image branch: never allocate an oversized buffer.
  if (item.sizeBytes > limits.maxFileBytes || data.length > Math.ceil(limits.maxFileBytes / 3) * 4)
    return tooLarge
  // A zero-byte file is a file; its canonical base64 is the empty string.
  if (data !== '' && !isCanonicalBase64Shape(data)) {
    return rejectFile('A file has invalid base64 data. Attach the original file again.')
  }
  const bytes = Buffer.from(data, 'base64')
  if (bytes.length > limits.maxFileBytes) return tooLarge
  if (bytes.toString('base64') !== data)
    return rejectFile('A file has invalid base64 data. Attach the original file again.')
  if (bytes.length !== item.sizeBytes)
    return rejectFile('A file does not match its declared size. Attach the original file again.')
  const hex = createHash('sha256').update(bytes).digest('hex')
  if (hex !== digest.hex) {
    return taskError(
      FileAttachmentErrorCode.DigestMismatch,
      'A file does not match its declared digest. Attach the original file again.'
    )
  }

  const declaredMediaType = item.mimeType === '' ? null : item.mimeType
  // The Host's classification is the only one used: `mismatch` compares the
  // declared type with the bytes, never with the client's own detection.
  const classification = classifyBytes({
    bytes,
    totalByteLength: bytes.length,
    declaredMediaType,
    filename: item.filename,
  })
  const reference = buildAttachmentFileReference({
    attachmentId: item.id,
    messageId: limits.messageId,
    name: item.filename,
    declaredMediaType,
    byteLength: bytes.length,
    digestHex: hex,
    classification,
  })
  if (!reference.ok) {
    // Every name problem the contract reports starts with "name "; any other
    // failure is not something the user can fix by renaming the file.
    return reference.message.startsWith('name ')
      ? rejectFile('A file attachment has an invalid name. Rename the file and attach it again.')
      : rejectFile(`A file attachment is invalid: ${reference.message}`)
  }
  return {
    ok: true,
    attachment: {
      id: item.id,
      kind: 'file',
      mimeType: item.mimeType,
      encoding: 'base64',
      dataBase64: data,
      filename: reference.value.name,
      sizeBytes: bytes.length,
      detectedMediaType: classification.detectedMediaType,
      digest: { algorithm: 'sha256', hex },
      fileReference: reference.value,
    },
  }
}

/** Reject the whole message rather than silently sending only part of it. */
export function validateIncomingAttachments(
  raw: unknown,
  limits: IncomingAttachmentLimits
): IncomingAttachmentValidation {
  if (raw == null) return { ok: true, attachments: undefined, fileReferences: [] }
  if (!Array.isArray(raw)) return rejectImage('Attachments must be a list.')
  if (!raw.length) return { ok: true, attachments: undefined, fileReferences: [] }
  // One ceiling over images and files together, checked before either branch.
  if (raw.length > limits.maxCount) {
    const carriesFiles = raw.some(item => isPlainRecord(item) && item.kind === 'file')
    return rejectImage(
      carriesFiles
        ? 'Too many attachments. Remove an attachment and try again.'
        : 'Too many image attachments. Remove an image and try again.'
    )
  }
  const attachments: Attachment[] = []
  const fileReferences: FileReferenceV1[] = []
  const ids = new Set<string>()
  for (const item of raw) {
    const result = !isPlainRecord(item)
      ? rejectImage('Only PNG or JPEG images encoded as base64 are supported.')
      : item.kind === 'file'
        ? validateFile(item, limits)
        : item.kind === 'image'
          ? validateImage(item, limits.maxBytes)
          : rejectImage('Only PNG or JPEG images encoded as base64 are supported.')
    if (!result.ok) return result
    // Ids name attachments in the ack and in tool calls, across both kinds.
    if (ids.has(result.attachment.id)) return rejectImage('Each attachment id must appear once.')
    ids.add(result.attachment.id)
    attachments.push(result.attachment)
    if (result.attachment.fileReference) fileReferences.push(result.attachment.fileReference)
  }
  return { ok: true, attachments, fileReferences }
}