tar-xz - v6.1.1
    Preparing search index...

    Function extractFile

    • Extract a tar.xz archive from disk to a target directory.

      Honors strip and filter from options.

      Path safety: refuses entries that escape cwd via "..", absolute paths, or pre-existing symlinks (leaf or ancestor). Hardlink linkSources are also validated.

      Threat model: assumes cwd is exclusively owned by this process for the duration of the call. Race conditions where a concurrent attacker process swaps ancestors during extraction are mitigated differently per platform:

      Parameters

      • archivePath: string

        Path to the .tar.xz file to extract

      • options: ExtractOptions & { cwd?: string } = {}

        Extraction options (strip, filter, cwd)

      Returns Promise<void>

      POSIX (Linux, macOS): FILE entries are written via open(O_WRONLY | O_CREAT | O_TRUNC | O_NOFOLLOW) + fd-based write() / chmod() / utimes(). O_NOFOLLOW prevents opening a symlink at the leaf path. The fd is held open for the entire content write, so the TOCTOU window is bounded to the gap between ensureSafeTarget and the open() call — effectively zero in practice.

      Windows: O_NOFOLLOW is not available. The Windows path uses open(target, 'wx', mode) (atomic exclusive create — O_CREAT | O_EXCL). If the target exists (EEXIST), it is unlinked and the open is retried. If the retry also fails with EEXIST, a symlink was injected between the unlink and the retry-open (symlink-swap race) and extraction fails closed with a security error. All write/chmod/utimes ops are fd-based (via FileHandle) so no by-path symlink follow can occur after the open. The residual race is limited to the open() syscall itself (sub-microsecond). See SECURITY.md§"Windows symlink-swap TOCTOU" for the full reparse-tag coverage table and user mitigations.

      Windows recommendation: extract to a directory owned exclusively by the calling process — do not extract user-supplied archives into shared or world-writable directories. For untrusted archives on Windows, prefer WSL.

    Settings

    Member Visibility