Skip to content

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

TypeScript
5.1 KB
Raw Blame
/**
 * S3-compatible object storage client for SOUL.md delivery.
 *
 * WRC downloads SOUL.md at reconciliation time (using its own RBAC access to
 * `clerum-storage-credentials`) and creates a ConfigMap in sandbox-recipes.
 * The coordinator Pod mounts this ConfigMap.
 * */
import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3'
import { Readable } from 'stream'

export interface StorageRef {
  bucket: string
  key: string
  provider: 's3' | 'gcs' | 'spaces' | 'minio'
  endpoint?: string
  region?: string
}

export interface StorageCredentials {
  accessKey: string
  secretKey: string
}

export class ObjectStorageClient {
  private readonly s3Client: S3Client

  constructor(
    private readonly credentials: StorageCredentials,
    private readonly storageRef: StorageRef
  ) {
    const endpoint = this.resolveEndpoint(storageRef)
    this.s3Client = new S3Client({
      region: storageRef.region ?? 'us-east-1',
      endpoint,
      credentials: {
        accessKeyId: credentials.accessKey,
        secretAccessKey: credentials.secretKey,
      },
      forcePathStyle: storageRef.provider === 'minio',
    })
  }

  // SEC-03: cap matches mcp-host MAX_SOUL_BYTES — prevents OOM during download
  // and avoids exceeding etcd's 1 MiB ConfigMap limit.
  private static readonly MAX_DOWNLOAD_BYTES = 64 * 1024

  async download(recipeName: string): Promise<Buffer> {
    this.enforceScopeConstraint(recipeName, this.storageRef.key)

    const command = new GetObjectCommand({
      Bucket: this.storageRef.bucket,
      Key: this.storageRef.key,
    })

    const response = await this.s3Client.send(command)

    if (!response.Body) {
      throw new Error(`Object storage returned empty body for key: ${this.storageRef.key}`)
    }

    try {
      return await this.streamToBuffer(
        response.Body as Readable,
        ObjectStorageClient.MAX_DOWNLOAD_BYTES
      )
    } finally {
      this.s3Client.destroy()
    }
  }

  private enforceScopeConstraint(recipeName: string, key: string): void {
    const requiredPrefix = `${recipeName}/`
    if (!key.startsWith(requiredPrefix)) {
      throw new ScopeConstraintError(
        `SOUL.md key '${key}' must start with '${requiredPrefix}'. ` +
          `This prevents cross-recipe data access.`,
        { recipeName, key, requiredPrefix }
      )
    }
  }

  private resolveEndpoint(ref: StorageRef): string | undefined {
    if (ref.endpoint) {
      // Security I-03 fix: validate endpoint to prevent SSRF — the endpoint field comes
      // from the CRD spec and could be attacker-controlled in a compromised cluster.
      let parsed: URL
      try {
        parsed = new URL(ref.endpoint)
      } catch {
        throw new Error(`Invalid storage endpoint URL: "${ref.endpoint}"`)
      }
      // Minio supports http for internal use; external providers must use HTTPS.
      if (ref.provider !== 'minio' && parsed.protocol !== 'https:') {
        throw new Error(
          `Storage endpoint must use HTTPS for provider "${ref.provider}": ${ref.endpoint}`
        )
      }
      // Block well-known SSRF targets: metadata services, cluster-internal DNS, loopback.
      const h = parsed.hostname.toLowerCase()
      if (
        h === 'localhost' ||
        h === '0.0.0.0' ||
        h === '127.0.0.1' ||
        h === '::1' ||
        h.startsWith('::ffff:127.') ||
        h.endsWith('.svc.cluster.local') ||
        h === 'metadata.google.internal' || // GCP IMDS
        h === '169.254.169.254' || // AWS/Azure IMDS
        h === '100.100.100.200' || // Alibaba Cloud IMDS
        h.startsWith('169.254.') || // entire link-local range
        // RFC1918 private IPv4 ranges
        h.startsWith('10.') ||
        h.startsWith('192.168.') ||
        (/^172\./.test(h) &&
          (() => {
            const o = parseInt(h.split('.')[1], 10)
            return o >= 16 && o <= 31
          })()) ||
        // IPv6 unique-local (fc00::/7)
        /^f[cd][0-9a-f]{2}:/i.test(h)
      ) {
        throw new Error(`Storage endpoint targets a disallowed internal address: ${ref.endpoint}`)
      }
      return ref.endpoint
    }
    if (ref.provider === 'spaces') return `https://${ref.region ?? 'nyc3'}.digitaloceanspaces.com`
    if (ref.provider === 'gcs') return 'https://storage.googleapis.com'
    return undefined // AWS S3 default
  }

  // Enforce the size cap before full buffering to keep object downloads bounded.
  private async streamToBuffer(stream: Readable, maxBytes: number): Promise<Buffer> {
    return new Promise((resolve, reject) => {
      const chunks: Buffer[] = []
      let total = 0
      stream.on('data', (chunk: Buffer) => {
        total += chunk.length
        if (total > maxBytes) {
          stream.destroy()
          reject(new Error(`SOUL.md exceeds maximum size (limit: ${maxBytes} bytes)`))
          return
        }
        chunks.push(chunk)
      })
      stream.on('end', () => resolve(Buffer.concat(chunks)))
      stream.on('error', reject)
    })
  }
}

export class ScopeConstraintError extends Error {
  constructor(
    message: string,
    public readonly context: Record<string, string>
  ) {
    super(message)
    this.name = 'ScopeConstraintError'
  }
}