archives.ts

/**
 * @fileoverview Generic archive extraction utilities.
 * Supports zip, tar, tar.gz, and tgz formats.
 */

import { createReadStream, existsSync } from 'node:fs'
import process from 'node:process'
import { pipeline } from 'node:stream/promises'
import { createGunzip } from 'node:zlib'

import { safeMkdir } from './fs'
import { normalizePath } from './paths/normalize'

import type AdmZipType from './external/adm-zip'
import type tarFsType from './external/tar-fs'

import {
  ArrayFrom,
  ArrayPrototypeSlice,
  ErrorCtor,
  PromiseAll,
  SetCtor,
  StringPrototypeEndsWith,
  StringPrototypeStartsWith,
} from './primordials'

/**
 * Archive format type.
 */
export type ArchiveFormat = 'tar' | 'tar.gz' | 'tgz' | 'zip'

/**
 * Options for archive extraction.
 */
export interface ExtractOptions {
  /** Suppress log messages */
  quiet?: boolean | undefined
  /** Strip leading path components (like tar --strip-components) */
  strip?: number | undefined
  /** Maximum number of entries to extract (default: 100,000) */
  maxEntries?: number | undefined
  /** Maximum size of a single extracted file in bytes (default: 100MB) */
  maxFileSize?: number | undefined
  /** Maximum total extracted size in bytes (default: 1GB) */
  maxTotalSize?: number | undefined
}

/**
 * Default extraction limits to prevent zip bombs and DoS attacks.
 */
// 100MB
const DEFAULT_MAX_FILE_SIZE = 100 * 1024 * 1024
// 1GB
const DEFAULT_MAX_TOTAL_SIZE = 1024 * 1024 * 1024
// Maximum number of entries to prevent inode exhaustion DoS.
const DEFAULT_MAX_ENTRIES = 100_000

let _AdmZip: typeof AdmZipType | undefined
let _tarFs: typeof tarFsType | undefined
let _path: typeof import('node:path') | undefined

/*@__NO_SIDE_EFFECTS__*/
function getAdmZip() {
  if (_AdmZip === undefined) {
    _AdmZip = /*@__PURE__*/ require('./external/adm-zip.js')
  }
  return _AdmZip!
}

/**
 * Lazily load the path module to avoid Webpack errors.
 *
 * @private
 */
/*@__NO_SIDE_EFFECTS__*/
function getPath() {
  if (_path === undefined) {
    _path = /*@__PURE__*/ require('node:path')
  }
  return _path as typeof import('node:path')
}

/*@__NO_SIDE_EFFECTS__*/
function getTarFs() {
  if (_tarFs === undefined) {
    _tarFs = /*@__PURE__*/ require('./external/tar-fs.js')
  }
  return _tarFs!
}

/**
 * Validate that a resolved path is within the target directory.
 * Prevents path traversal attacks.
 *
 * @param targetPath - The resolved path to validate
 * @param baseDir - The base directory that should contain the path
 * @param entryName - Original entry name for error reporting
 * @throws Error if path is outside the base directory
 * @private
 */
function validatePathWithinBase(
  targetPath: string,
  baseDir: string,
  entryName: string,
): void {
  const path = getPath()
  const resolvedTarget = path.resolve(targetPath)
  const resolvedBase = path.resolve(baseDir)

  // Ensure target path starts with base directory + separator
  // This prevents attacks like /base/dir vs /base/dir-evil
  if (
    !StringPrototypeStartsWith(resolvedTarget, resolvedBase + path.sep) &&
    resolvedTarget !== resolvedBase
  ) {
    throw new ErrorCtor(
      `Path traversal attempt detected: entry "${entryName}" would extract to "${resolvedTarget}" outside target directory "${resolvedBase}"`,
    )
  }
}

/**
 * Assert that an archive file exists on disk before handing it to the
 * underlying extractor. Normalizes the "missing archive" surface across
 * all three extractors (zip/tar/tar.gz): each now throws a Node-style
 * `ENOENT` error with the archive path. Without this preflight, `zip`
 * goes through adm-zip and surfaces as `"Invalid filename"`, while
 * `tar`/`tar.gz` surface the raw Node `ENOENT` — inconsistent, and
 * adm-zip's message didn't include the path.
 *
 * @throws Error with `code: 'ENOENT'` if archivePath doesn't exist.
 * @private
 */
function assertArchiveExists(archivePath: string): void {
  if (!existsSync(archivePath)) {
    const err = new ErrorCtor(
      `ENOENT: no such file or directory, open '${archivePath}'`,
    ) as Error & { code: string; path: string }
    err.code = 'ENOENT'
    err.path = archivePath
    throw err
  }
}

/**
 * Detect archive format from file path.
 *
 * @param filePath - Path to archive file
 * @returns Archive format or null if unknown
 *
 * @example
 * ```typescript
 * detectArchiveFormat('package.tar.gz')  // 'tar.gz'
 * detectArchiveFormat('archive.zip')     // 'zip'
 * detectArchiveFormat('data.csv')        // null
 * ```
 */
export function detectArchiveFormat(filePath: string): ArchiveFormat | null {
  const lower = filePath.toLowerCase()
  if (StringPrototypeEndsWith(lower, '.tar.gz')) {
    return 'tar.gz'
  }
  if (StringPrototypeEndsWith(lower, '.tgz')) {
    return 'tgz'
  }
  if (StringPrototypeEndsWith(lower, '.tar')) {
    return 'tar'
  }
  if (StringPrototypeEndsWith(lower, '.zip')) {
    return 'zip'
  }
  return null
}

/**
 * Extract an archive to a directory.
 * Automatically detects format from file extension.
 *
 * @param archivePath - Path to archive file
 * @param outputDir - Directory to extract to
 * @param options - Extraction options
 * @throws Error if archive format is not supported
 *
 * @example
 * ```typescript
 * await extractArchive('/tmp/package.tar.gz', '/tmp/output')
 * await extractArchive('/tmp/release.zip', '/tmp/output', { strip: 1 })
 * ```
 */
export async function extractArchive(
  archivePath: string,
  outputDir: string,
  options: ExtractOptions = {},
): Promise<void> {
  const format = detectArchiveFormat(archivePath)

  if (!format) {
    const path = getPath()
    const ext = path.extname(archivePath).toLowerCase()
    throw new ErrorCtor(
      `Unsupported archive format${ext ? ` (extension: ${ext})` : ''}: ${archivePath}. ` +
        'Supported formats: .zip, .tar, .tar.gz, .tgz',
    )
  }

  switch (format) {
    case 'zip':
      return await extractZip(archivePath, outputDir, options)
    case 'tar':
      return await extractTar(archivePath, outputDir, options)
    case 'tar.gz':
    case 'tgz':
      return await extractTarGz(archivePath, outputDir, options)
  }
}

/**
 * Extract a tar archive to a directory.
 *
 * @param archivePath - Path to tar file
 * @param outputDir - Directory to extract to
 * @param options - Extraction options
 *
 * @example
 * ```typescript
 * await extractTar('/tmp/archive.tar', '/tmp/output')
 * await extractTar('/tmp/archive.tar', '/tmp/output', { strip: 1 })
 * ```
 */
export async function extractTar(
  archivePath: string,
  outputDir: string,
  options: ExtractOptions = {},
): Promise<void> {
  // Normalize the "missing archive" surface (see extractZip) — throw
  // ENOENT up front with a clear message rather than letting the
  // Node-level createReadStream eventually surface as a stream error.
  assertArchiveExists(archivePath)

  const {
    maxEntries = DEFAULT_MAX_ENTRIES,
    maxFileSize = DEFAULT_MAX_FILE_SIZE,
    maxTotalSize = DEFAULT_MAX_TOTAL_SIZE,
    strip = 0,
  } = options

  // Normalize output directory path for cross-platform compatibility
  const normalizedOutputDir = normalizePath(outputDir)
  await safeMkdir(normalizedOutputDir)

  let totalExtractedSize = 0
  let entryCount = 0

  let destroyScheduled = false

  const tarFs = getTarFs()
  const extractStream = tarFs.extract(normalizedOutputDir, {
    map: (header: { name: string; size?: number; type?: string }) => {
      // Skip if destroy already scheduled
      if (destroyScheduled) {
        return header
      }

      // Check entry count to prevent inode exhaustion DoS.
      entryCount += 1
      if (entryCount > maxEntries) {
        destroyScheduled = true
        process.nextTick(() => {
          extractStream.destroy(
            new Error(
              `Archive has too many entries: exceeded limit of ${maxEntries}`,
            ),
          )
        })
        return header
      }

      // Reject entries with null bytes in names (defense in depth).
      if (header.name.includes('\0')) {
        destroyScheduled = true
        process.nextTick(() => {
          extractStream.destroy(
            new Error(
              `Invalid null byte in archive entry name: ${header.name}`,
            ),
          )
        })
        return header
      }

      // Check for symlinks
      if (header.type === 'symlink' || header.type === 'link') {
        destroyScheduled = true
        process.nextTick(() => {
          extractStream.destroy(
            new Error(
              `Symlink detected in archive: ${header.name}. Symlinks are not supported for security reasons.`,
            ),
          )
        })
        return header
      }

      // Check individual file size
      if (header.size && header.size > maxFileSize) {
        destroyScheduled = true
        process.nextTick(() => {
          extractStream.destroy(
            new Error(
              `File size exceeds limit: ${header.name} (${header.size} bytes > ${maxFileSize} bytes)`,
            ),
          )
        })
        return header
      }

      // Check total extracted size
      if (header.size) {
        totalExtractedSize += header.size
        if (totalExtractedSize > maxTotalSize) {
          destroyScheduled = true
          process.nextTick(() => {
            extractStream.destroy(
              new Error(
                `Total extracted size exceeds limit: ${totalExtractedSize} bytes > ${maxTotalSize} bytes`,
              ),
            )
          })
          return header
        }
      }

      return header
    },
    strip,
  })

  // Attach error handler before starting pipeline to catch errors
  extractStream.on('error', () => {
    // Error will be caught by pipeline
  })

  const readStream = createReadStream(archivePath)

  try {
    await pipeline(readStream, extractStream)
  } catch (e) {
    // Ensure stream is cleaned up on error
    readStream.destroy()
    throw e
  }
}

/**
 * Extract a gzipped tar archive to a directory.
 *
 * @param archivePath - Path to tar.gz or tgz file
 * @param outputDir - Directory to extract to
 * @param options - Extraction options
 *
 * @example
 * ```typescript
 * await extractTarGz('/tmp/archive.tar.gz', '/tmp/output')
 * await extractTarGz('/tmp/archive.tgz', '/tmp/output', { strip: 1 })
 * ```
 */
export async function extractTarGz(
  archivePath: string,
  outputDir: string,
  options: ExtractOptions = {},
): Promise<void> {
  // Normalize the "missing archive" surface (see extractZip).
  assertArchiveExists(archivePath)

  const {
    maxEntries = DEFAULT_MAX_ENTRIES,
    maxFileSize = DEFAULT_MAX_FILE_SIZE,
    maxTotalSize = DEFAULT_MAX_TOTAL_SIZE,
    strip = 0,
  } = options

  // Normalize output directory path for cross-platform compatibility
  const normalizedOutputDir = normalizePath(outputDir)
  await safeMkdir(normalizedOutputDir)

  let totalExtractedSize = 0
  let entryCount = 0

  let destroyScheduled = false

  const tarFs = getTarFs()
  const extractStream = tarFs.extract(normalizedOutputDir, {
    map: (header: { name: string; size?: number; type?: string }) => {
      // Skip if destroy already scheduled
      if (destroyScheduled) {
        return header
      }

      // Check entry count to prevent inode exhaustion DoS.
      entryCount += 1
      if (entryCount > maxEntries) {
        destroyScheduled = true
        process.nextTick(() => {
          extractStream.destroy(
            new Error(
              `Archive has too many entries: exceeded limit of ${maxEntries}`,
            ),
          )
        })
        return header
      }

      // Reject entries with null bytes in names (defense in depth).
      if (header.name.includes('\0')) {
        destroyScheduled = true
        process.nextTick(() => {
          extractStream.destroy(
            new Error(
              `Invalid null byte in archive entry name: ${header.name}`,
            ),
          )
        })
        return header
      }

      // Check for symlinks
      if (header.type === 'symlink' || header.type === 'link') {
        destroyScheduled = true
        process.nextTick(() => {
          extractStream.destroy(
            new Error(
              `Symlink detected in archive: ${header.name}. Symlinks are not supported for security reasons.`,
            ),
          )
        })
        return header
      }

      // Check individual file size
      if (header.size && header.size > maxFileSize) {
        destroyScheduled = true
        process.nextTick(() => {
          extractStream.destroy(
            new Error(
              `File size exceeds limit: ${header.name} (${header.size} bytes > ${maxFileSize} bytes)`,
            ),
          )
        })
        return header
      }

      // Check total extracted size
      if (header.size) {
        totalExtractedSize += header.size
        if (totalExtractedSize > maxTotalSize) {
          destroyScheduled = true
          process.nextTick(() => {
            extractStream.destroy(
              new Error(
                `Total extracted size exceeds limit: ${totalExtractedSize} bytes > ${maxTotalSize} bytes`,
              ),
            )
          })
          return header
        }
      }

      return header
    },
    strip,
  })

  // Attach error handler before starting pipeline to catch errors
  extractStream.on('error', () => {
    // Error will be caught by pipeline
  })

  const readStream = createReadStream(archivePath)

  try {
    await pipeline(readStream, createGunzip(), extractStream)
  } catch (e) {
    // Ensure stream is cleaned up on error
    readStream.destroy()
    throw e
  }
}

/**
 * Extract a zip archive to a directory.
 *
 * @param archivePath - Path to zip file
 * @param outputDir - Directory to extract to
 * @param options - Extraction options
 *
 * @example
 * ```typescript
 * await extractZip('/tmp/archive.zip', '/tmp/output')
 * await extractZip('/tmp/archive.zip', '/tmp/output', { strip: 1 })
 * ```
 */
export async function extractZip(
  archivePath: string,
  outputDir: string,
  options: ExtractOptions = {},
): Promise<void> {
  // Normalize the "missing archive" surface — throws ENOENT before
  // AdmZip can surface its generic "Invalid filename" message.
  assertArchiveExists(archivePath)

  const {
    maxEntries = DEFAULT_MAX_ENTRIES,
    maxFileSize = DEFAULT_MAX_FILE_SIZE,
    maxTotalSize = DEFAULT_MAX_TOTAL_SIZE,
    strip = 0,
  } = options

  // Normalize output directory path for cross-platform compatibility
  const normalizedOutputDir = normalizePath(outputDir)
  await safeMkdir(normalizedOutputDir)

  const AdmZip = getAdmZip()
  const zip = new AdmZip(archivePath)
  const path = getPath()

  // Pre-validate all entries for security
  const entries = zip.getEntries()

  // Check entry count to prevent inode exhaustion DoS.
  if (entries.length > maxEntries) {
    throw new ErrorCtor(
      `Archive has too many entries: ${entries.length} (limit: ${maxEntries})`,
    )
  }

  let totalExtractedSize = 0

  for (const entry of entries) {
    if (entry.isDirectory) {
      continue
    }

    // Reject entries with null bytes in names (defense in depth).
    if (entry.entryName.includes('\0')) {
      throw new ErrorCtor(
        `Invalid null byte in archive entry name: ${entry.entryName}`,
      )
    }

    // Check individual file size
    const uncompressedSize = entry.header.size
    if (uncompressedSize > maxFileSize) {
      throw new ErrorCtor(
        `File size exceeds limit: ${entry.entryName} (${uncompressedSize} bytes > ${maxFileSize} bytes)`,
      )
    }

    // Check total extracted size
    totalExtractedSize += uncompressedSize
    if (totalExtractedSize > maxTotalSize) {
      throw new ErrorCtor(
        `Total extracted size exceeds limit: ${totalExtractedSize} bytes > ${maxTotalSize} bytes`,
      )
    }

    // ZIP entries always use forward slashes per ZIP specification
    const parts = entry.entryName.split('/')
    if (parts.length <= strip) {
      continue
    }

    const strippedPath = ArrayPrototypeSlice(parts, strip).join('/')
    const targetPath = path.join(normalizedOutputDir, strippedPath)

    // Validate path is within target directory (prevents path traversal)
    validatePathWithinBase(targetPath, normalizedOutputDir, entry.entryName)
  }

  if (strip === 0) {
    // Simple case: extract everything as-is
    // Even without strip, validate paths
    for (const entry of entries) {
      if (!entry.isDirectory) {
        const targetPath = path.join(normalizedOutputDir, entry.entryName)
        validatePathWithinBase(targetPath, normalizedOutputDir, entry.entryName)
      }
    }

    zip.extractAllTo(normalizedOutputDir, true)
  } else {
    // Strip leading path components
    const path = getPath()
    const entries = zip.getEntries()

    // Collect all directories we need to create
    const dirsToCreate = new SetCtor<string>()
    for (const entry of entries) {
      if (entry.isDirectory) {
        continue
      }

      // ZIP entries always use forward slashes per ZIP specification
      const parts = entry.entryName.split('/')
      if (parts.length <= strip) {
        continue
      }

      const strippedPath = ArrayPrototypeSlice(parts, strip).join('/')
      const targetPath = path.join(normalizedOutputDir, strippedPath)
      dirsToCreate.add(path.dirname(targetPath))
    }

    // Create all directories
    await PromiseAll(ArrayFrom(dirsToCreate).map(dir => safeMkdir(dir)))

    // Extract all files (synchronous operation)
    for (const entry of entries) {
      if (entry.isDirectory) {
        continue
      }

      // ZIP entries always use forward slashes per ZIP specification
      const parts = entry.entryName.split('/')
      if (parts.length <= strip) {
        continue
      }

      const strippedPath = ArrayPrototypeSlice(parts, strip).join('/')
      const targetPath = path.join(normalizedOutputDir, strippedPath)

      // Extract file
      zip.extractEntryTo(entry, path.dirname(targetPath), false, true)
    }
  }
}