Skip to content

armgit / E2B

Public Imported from GitHub
0

Open-source, secure environment with real-world tools for enterprise-grade agents.

18.0 KB
Raw Blame
import crypto from 'node:crypto'
import fs from 'node:fs'
import os from 'node:os'
import path from 'node:path'
import url from 'node:url'
import { parse, type StackFrame } from 'error-stack-parser-es'
import { dynamicImport } from '../utils'
import { TemplateError } from '../errors'
import { BASE_STEP_NAME, FINALIZE_STEP_NAME } from './consts'
import { PatternMatcher } from '@e2b/dockerfile-utils'
import type { IgnoreLike, Path } from 'glob'
import type { BuildOptions } from './types'

/**
 * Validate that a source path for copy operations is a relative path that stays
 * within the context directory. This prevents path traversal attacks and ensures
 * files are copied from within the expected directory.
 *
 * @param src The source path to validate
 * @param stackTrace Optional stack trace for error reporting
 * @throws TemplateError if the path is absolute or escapes the context directory
 *
 * Invalid paths:
 * - Absolute paths: /absolute/path, C:\Windows\path
 * - Parent directory escapes: ../foo, foo/../../bar, ./foo/../../../bar
 *
 * Valid paths:
 * - Simple relative: foo, foo/bar
 * - Current directory prefix: ./foo, ./foo/bar
 * - Internal parent refs that don't escape: foo/../bar (stays within context)
 */
export function validateRelativePath(
  src: string,
  stackTrace: string | undefined
): void {
  // Check for absolute paths using Node's cross-platform implementation
  if (path.isAbsolute(src)) {
    const error = new TemplateError(
      `Invalid source path "${src}": absolute paths are not allowed. Use a relative path within the context directory.`,
      stackTrace
    )
    throw error
  }

  // Normalize the path and check if it escapes the context directory
  const normalized = path.normalize(src)

  // After normalization, a path that escapes would be '..' or start with '../'
  // We check for '..' followed by path separator to avoid false positives on filenames like '..myconfig'
  // Examples:
  // - '../foo' -> '../foo' (escapes)
  // - 'foo/../../bar' -> '../bar' (escapes)
  // - './foo/../../../bar' -> '../../bar' (escapes)
  // - 'foo/../bar' -> 'bar' (doesn't escape)
  // - './foo/bar' -> 'foo/bar' (doesn't escape)
  // - '..myconfig' -> '..myconfig' (valid filename, doesn't escape)
  const escapes = normalized === '..' || normalized.startsWith('..' + path.sep)

  if (escapes) {
    const error = new TemplateError(
      `Invalid source path "${src}": path escapes the context directory. The path must stay within the context directory.`,
      stackTrace
    )
    throw error
  }
}

/**
 * Normalize build arguments from different overload signatures.
 * Handles string name or legacy options object with alias.
 *
 * @param nameOrOptions Name or legacy options with alias
 * @param options Optional build options (when first arg is name)
 * @returns Object with normalized name, tags, and build options
 * @throws TemplateError if no template name is provided
 */
export function normalizeBuildArguments(
  nameOrOptions: string | BuildOptions,
  options?: Omit<BuildOptions, 'alias'>
): {
  name: string
  buildOptions: Omit<BuildOptions, 'alias'>
} {
  let name: string
  let buildOptions: Omit<BuildOptions, 'alias'>

  if (typeof nameOrOptions === 'string') {
    name = nameOrOptions
    buildOptions = options ?? {}
  } else {
    // Legacy: options object with alias
    const { alias, ...restOpts } = nameOrOptions
    name = alias
    buildOptions = restOpts
  }

  if (!name || name.length === 0) {
    throw new TemplateError('Name must be provided')
  }

  return { name, buildOptions }
}

/**
 * Read and parse a .dockerignore file.
 *
 * @param contextPath Directory path containing the .dockerignore file
 * @returns Array of ignore patterns (empty lines and comments are filtered out)
 */
export function readDockerignore(contextPath: string): string[] {
  const dockerignorePath = path.join(contextPath, '.dockerignore')
  if (!fs.existsSync(dockerignorePath)) {
    return []
  }

  const content = fs
    .readFileSync(dockerignorePath, 'utf-8')
    .replace(/^\uFEFF/, '')
  return content
    .split('\n')
    .filter((line) => !line.startsWith('#'))
    .map((line) => line.trim())
    .filter((line) => line)
}

/**
 * Normalize path separators to forward slashes for glob patterns (glob expects / even on Windows)
 * @param path - The path to normalize
 * @returns The normalized path
 */
function normalizePath(path: string): string {
  return path.replace(/\\/g, '/')
}

function normalizeIgnorePattern(pattern: string, contextPath: string): string {
  let trimmed = pattern.trim()
  const negated = trimmed.startsWith('!')
  if (negated) {
    trimmed = trimmed.slice(1).trim()
  }
  // Absolute patterns pointing into the context are made relative to it.
  // Other patterns are anchored at the context root, a leading `/` is ignored.
  if (path.isAbsolute(trimmed)) {
    const relative = path.relative(contextPath, trimmed)
    if (
      relative !== '' &&
      relative !== '..' &&
      !relative.startsWith(`..${path.sep}`) &&
      !path.isAbsolute(relative)
    ) {
      trimmed = relative
    }
  }
  return (negated ? '!' : '') + trimmed
}

/**
 * Create a glob `ignore` matcher that follows `.dockerignore` semantics:
 * patterns are relative to the context root, a pattern matching a directory
 * excludes everything under it, and `!` patterns re-include paths
 * (the last matching pattern wins). The context root is never excluded.
 *
 * @param ignorePatterns Ignore patterns in `.dockerignore` syntax
 * @param contextPath Base directory the patterns are relative to
 * @returns Matcher to pass as the glob `ignore` option
 */
function createIgnoreMatcher(
  ignorePatterns: string[],
  contextPath: string
): IgnoreLike {
  const absoluteContextPath = path.resolve(contextPath)
  let matcher: PatternMatcher
  try {
    matcher = new PatternMatcher(
      ignorePatterns.map((pattern) =>
        normalizeIgnorePattern(pattern, absoluteContextPath)
      ),
      { backslashIsSeparator: path.sep === '\\' }
    )
  } catch (err) {
    throw new TemplateError((err as Error).message)
  }

  const ignored = (p: Path) => {
    const relativePath = p.relativePosix()
    return relativePath !== '' && matcher.matches(relativePath)
  }

  return {
    ignored,
    childrenIgnored: (p) =>
      ignored(p) && !matcher.mayMatchUnder(p.relativePosix()),
  }
}

/**
 * Get all files for a given path and ignore patterns.
 *
 * @param src Path to the source directory
 * @param contextPath Base directory for resolving relative paths
 * @param ignorePatterns Ignore patterns in `.dockerignore` syntax
 * @returns Array of files
 */
export async function getAllFilesInPath(
  src: string,
  contextPath: string,
  ignorePatterns: string[],
  includeDirectories: boolean = true
) {
  const { glob } = await dynamicImport<typeof import('glob')>('glob')
  const files = new Map<string, Path>()
  const ignore = createIgnoreMatcher(ignorePatterns, contextPath)

  const globFiles = await glob(src, {
    ignore,
    withFileTypes: true,
    dot: true,
    cwd: contextPath,
  })

  // Visit parents before their children, so paths under an already walked
  // directory are not walked again
  const depth = (p: Path) => {
    const relativePath = p.relativePosix()
    return relativePath === '' ? 0 : relativePath.split('/').length
  }
  globFiles.sort((a, b) => depth(a) - depth(b))
  const walkedDirs = new Set<string>()
  const isUnderWalkedDir = (relativePath: string) => {
    if (walkedDirs.has('')) {
      return true
    }
    for (
      let parent = path.posix.dirname(relativePath);
      parent !== '.' && parent !== '/';
      parent = path.posix.dirname(parent)
    ) {
      if (walkedDirs.has(parent)) {
        return true
      }
    }
    return false
  }

  for (const file of globFiles) {
    if (isUnderWalkedDir(file.relativePosix())) {
      continue
    }
    if (file.isDirectory()) {
      walkedDirs.add(file.relativePosix())
      // For directories, add the directory itself and all files inside it
      if (includeDirectories) {
        files.set(file.fullpath(), file)
      }
      const dirPattern = normalizePath(
        // When the matched directory is '.', `file.relative()` can be an empty string.
        // In that case, we want to match all files under the current directory instead of
        // creating an absolute glob like '/**/*' which would traverse the entire filesystem.
        path.join(file.relative() || '.', '**/*')
      )
      const dirFiles = await glob(dirPattern, {
        ignore,
        withFileTypes: true,
        dot: true,
        cwd: contextPath,
      })
      dirFiles.forEach((f) => files.set(f.fullpath(), f))
    } else {
      // For files, just add the file
      files.set(file.fullpath(), file)
    }
  }

  // Sort by full path for a deterministic order — the default sort() would
  // stringify the Path objects to '[object Object]' and keep glob order,
  // making the files hash dependent on filesystem traversal order.
  return Array.from(files.values()).sort((a, b) =>
    a.fullpath() < b.fullpath() ? -1 : a.fullpath() > b.fullpath() ? 1 : 0
  )
}

/**
 * Calculate a hash of files being copied to detect changes for cache invalidation.
 * The hash includes file content, metadata (mode, size), and relative paths.
 * Note: uid, gid, and mtime are excluded to ensure stable hashes across environments.
 *
 * @param src Source path pattern for files to copy
 * @param dest Destination path where files will be copied
 * @param contextPath Base directory for resolving relative paths
 * @param ignorePatterns Ignore patterns in `.dockerignore` syntax
 * @param resolveSymlinks Whether to resolve symbolic links when hashing
 * @param stackTrace Optional stack trace for error reporting
 * @returns Hex string hash of all files
 * @throws Error if no files match the source pattern
 */
export async function calculateFilesHash(
  src: string,
  dest: string,
  contextPath: string,
  ignorePatterns: string[],
  resolveSymlinks: boolean,
  stackTrace: string | undefined
): Promise<string> {
  const srcPath = path.join(contextPath, src)
  const hash = crypto.createHash('sha256')
  const content = `COPY ${src} ${dest}`

  hash.update(content)

  const files = await getAllFilesInPath(src, contextPath, ignorePatterns, true)

  if (files.length === 0) {
    const error = new Error(`No files found in ${srcPath}`)
    if (stackTrace) {
      error.stack = stackTrace
    }
    throw error
  }

  // Hash stats - only include stable metadata (mode, size)
  // Exclude uid, gid, and mtime to ensure consistent hashes across environments
  const hashStats = (stats: fs.Stats) => {
    hash.update(stats.mode.toString())
    // A directory's size depends on the filesystem, not on the copied files
    if (!stats.isDirectory()) {
      hash.update(stats.size.toString())
    }
  }

  // Process files recursively
  for (const file of files) {
    // Add a relative path to hash calculation
    const relativePath = file.relativePosix()
    hash.update(relativePath)

    // Add stat information to hash calculation
    if (file.isSymbolicLink()) {
      // If the symlink is broken, it will return undefined, otherwise it will return a stats object of the target
      const stats = fs.statSync(file.fullpath(), { throwIfNoEntry: false })
      const shouldFollow =
        resolveSymlinks && (stats?.isFile() || stats?.isDirectory())

      if (!shouldFollow) {
        const stats = fs.lstatSync(file.fullpath())

        hashStats(stats)

        const content = fs.readlinkSync(file.fullpath())
        hash.update(content)

        continue
      }
    }

    const stats = fs.statSync(file.fullpath())
    hashStats(stats)

    // Add file content to hash calculation
    if (stats.isFile()) {
      const content = fs.readFileSync(file.fullpath())
      hash.update(new Uint8Array(content))
    }
  }

  return hash.digest('hex')
}

/**
 * Convert a stack-trace file name to a filesystem path.
 * In ESM modules, stack frames report file:// URLs.
 */
function frameFileToPath(fileName: string): string {
  return fileName.startsWith('file:') ? url.fileURLToPath(fileName) : fileName
}

/**
 * Check whether a stack-trace file name refers to user code, i.e. a file
 * outside the SDK's own directory. Node internals (`node:*`) and native
 * frames are never user code.
 */
function isUserFile(fileName: string, sdkDir: string): boolean {
  if (fileName.startsWith('node:') || fileName === 'native') {
    return false
  }
  try {
    const relative = path.relative(
      sdkDir,
      path.dirname(frameFileToPath(fileName))
    )
    return (
      relative !== '' &&
      (relative.startsWith('..') || path.isAbsolute(relative))
    )
  } catch {
    return false
  }
}

/**
 * Capture the current stack and locate the first frame in user code.
 *
 * Frames are selected by boundary rather than by fixed depth: the SDK's own
 * directory is derived from the top frame (which is always SDK code — this
 * module), and the first frame whose file lies outside it is the user's call
 * site. This keeps the result stable when transpilers inject extra frames
 * (e.g. TS class-field initializers) or runtimes elide delegating frames
 * (e.g. Bun's tail-call elision).
 *
 * @returns Parsed frames and the index of the user's frame, -1 when no user
 *   frame is identifiable (e.g. the SDK is bundled into the caller's file)
 */
function captureUserFrames(): {
  frames: StackFrame[]
  userFrameIndex: number
} {
  const frames = parse(new Error(), { allowEmpty: true })
  const ownFile = frames[0]?.fileName
  if (!ownFile) {
    return { frames, userFrameIndex: -1 }
  }
  const sdkDir = path.dirname(frameFileToPath(ownFile))

  const userFrameIndex = frames.findIndex(
    (frame) =>
      frame.fileName !== undefined && isUserFile(frame.fileName, sdkDir)
  )
  return { frames, userFrameIndex }
}

/**
 * Get the stack trace starting at the caller's frame in user code.
 *
 * @returns The stack trace starting at the user's frame, or undefined when no
 *   user frame is identifiable
 */
export function getCallerFrame(): string | undefined {
  const { frames, userFrameIndex } = captureUserFrames()
  if (userFrameIndex === -1) {
    return
  }

  return frames
    .slice(userFrameIndex)
    .map((frame) => frame.source)
    .filter((source): source is string => source !== undefined)
    .join('\n')
}

/**
 * Get the directory of the caller in user code.
 *
 * @returns The caller's directory path, or undefined if not available
 */
export function getCallerDirectory(): string | undefined {
  const { frames, userFrameIndex } = captureUserFrames()
  const fileName =
    userFrameIndex === -1 ? undefined : frames[userFrameIndex].fileName
  if (!fileName) {
    return undefined
  }

  return path.dirname(frameFileToPath(fileName))
}

/**
 * Convert a numeric file mode to a zero-padded octal string.
 *
 * @param mode File mode as a number (e.g., 493 for 0o755)
 * @returns Zero-padded 4-digit octal string (e.g., "0755")
 *
 * @example
 * ```ts
 * padOctal(0o755) // Returns "0755"
 * padOctal(0o644) // Returns "0644"
 * ```
 */
export function padOctal(mode: number): string {
  return mode.toString(8).padStart(4, '0')
}

/**
 * Create a gzipped tar archive of files matching a pattern, spooled to a
 * temporary file on disk.
 *
 * Spooling instead of buffering keeps memory bounded and gives the archive a
 * known size, so the upload can send an exact `Content-Length`. The caller
 * owns the archive's lifetime and must invoke `cleanup` once done with it.
 * This mirrors the Python SDK's `tar_file_stream`.
 *
 * @param fileName Glob pattern for files to include
 * @param fileContextPath Base directory for resolving file paths
 * @param ignorePatterns Ignore patterns to exclude from the archive
 * @param resolveSymlinks Whether to follow symbolic links
 * @param gzip Whether to gzip the archive
 * @returns The archive path, its size in bytes, and a cleanup callback that
 *   removes the spooled archive. Cleanup is best-effort so it can never mask
 *   the upload result — a leaked temp dir is non-fatal, the OS reclaims it.
 */
export async function spoolTarArchive(
  fileName: string,
  fileContextPath: string,
  ignorePatterns: string[],
  resolveSymlinks: boolean,
  gzip: boolean
): Promise<{ path: string; size: number; cleanup: () => Promise<void> }> {
  const { create } = await dynamicImport<typeof import('tar')>('tar')

  const allFiles = await getAllFilesInPath(
    fileName,
    fileContextPath,
    ignorePatterns,
    true
  )

  const filePaths = allFiles.map((file) => file.relativePosix())

  const tmpDir = await fs.promises.mkdtemp(
    path.join(os.tmpdir(), 'e2b-template-')
  )
  const tarPath = path.join(tmpDir, 'context.tar.gz')
  const cleanup = () =>
    fs.promises.rm(tmpDir, { recursive: true, force: true }).catch(() => {})

  try {
    await create(
      {
        gzip,
        cwd: fileContextPath,
        follow: resolveSymlinks,
        noDirRecurse: true,
        file: tarPath,
      },
      filePaths
    )

    const { size } = await fs.promises.stat(tarPath)
    return { path: tarPath, size, cleanup }
  } catch (err) {
    await cleanup()
    throw err
  }
}

/**
 * Get the array index for a build step based on its name.
 *
 * Special steps:
 * - BASE_STEP_NAME: Returns 0 (first step)
 * - FINALIZE_STEP_NAME: Returns the last index
 * - Numeric strings: Converted to number
 *
 * @param step Build step name or number as string
 * @param stackTracesLength Total number of stack traces (used for FINALIZE_STEP_NAME)
 * @returns Index for the build step
 */
export function getBuildStepIndex(
  step: string,
  stackTracesLength: number
): number {
  if (step === BASE_STEP_NAME) {
    return 0
  }

  if (step === FINALIZE_STEP_NAME) {
    return stackTracesLength - 1
  }

  return Number(step)
}

/**
 * Read GCP service account JSON from a file or object.
 *
 * @param contextPath Base directory for resolving relative file paths
 * @param pathOrContent Either a path to a JSON file or a service account object
 * @returns Service account JSON as a string
 */
export function readGCPServiceAccountJSON(
  contextPath: string,
  pathOrContent: string | object
): string {
  if (typeof pathOrContent === 'string') {
    return fs.readFileSync(path.join(contextPath, pathOrContent), 'utf-8')
  }
  return JSON.stringify(pathOrContent)
}