tar-fs

tar-fs is the filesystem layer on top of tar-stream, the low-level tar format encoder/decoder from the same author. Where tar-stream deals purely in tar headers and byte streams, tar-fs walks a real directory tree, turns files, directories, and symlinks into tar entries, and — on the way back — recreates that tree on disk with correct permissions, ownership, and modification times.

The module exposes exactly two functions, pack and extract, each returning a stream that can be piped directly into or out of fs.createReadStream/fs.createWriteStream. Packing walks a directory with a queue-based traversal that supports filtering, sorting, path stripping, and per-entry header/content transforms. Extraction listens on a tar-stream extract() instance and recreates directories, files, hardlinks, and symlinks, applying dmode/fmode, chown, and utimes as it goes.

Because tar archives can encode entries that point outside the extraction directory (the classic “zip-slip” path-traversal bug), tar-fs validates every resolved path, symlink target, and hardlink target against the extraction root before writing, and can reject archives that try to escape it. It also strips setuid/setgid/sticky bits during extraction by default. This makes it a common choice anywhere an application needs to safely accept and unpack a tarball from an untrusted source, not just move files around locally.

With tens of millions of weekly downloads, tar-fs sits underneath a large slice of the Node.js ecosystem’s tooling for packaging, Docker-adjacent image handling, and dependency installation — used wherever code needs to turn a directory into a tarball, or a tarball back into a directory, without shelling out to the system tar binary.

What You Get

• Two focused stream factories, pack() and extract(), with no classes or global state to manage
• Directory traversal with ignore/filter, entries (explicit file lists), and sort options for controlling exactly what gets packed
• Header and content transforms via map and mapStream, so callers can rewrite entry names, permissions, or file contents mid-stream
• Path-traversal protection on extract — symlink, hardlink, and directory targets are validated against the extraction root before anything is written
• Cross-runtime filesystem support: optional bare-fs/bare-path bindings let the same code run under the Bare JavaScript runtime, not just Node.js

Common Use Cases

• Packaging a build output or project directory into a .tar for publishing or distribution
• Safely extracting a tarball fetched from a registry or an untrusted upload without risking path-traversal writes outside the target directory
• Copying a directory tree with permissions, ownership, and mtimes intact via tar.pack(src).pipe(tar.extract(dest))
• Rewriting paths and permissions during extraction, e.g. stripping a leading directory prefix (strip) or forcing readable-only output (readable)

Under The Hood

Architecture tar-fs is a single flat CommonJS module that exports two independent stream factories, pack and extract, with no shared class hierarchy. pack drives a queue-based statAll traversal (in index.js) that walks the directory breadth-first, lstat/stat-ing each path, applying the caller’s ignore/sort options, and feeding results into a tar-stream pack() instance one entry at a time via pump. extract takes the inverse path: it attaches an entry listener to a tar-stream extract() instance and, for each header, resolves the target path, recursively validates it via validate/validateNotSymlink (walking up the path checking for pre-existing symlinks that could redirect writes), creates the containing directory tree with mkdirfix, and then dispatches to onfile/onlink/onsymlink handlers that write content, set ownership/permissions (chperm), and restore timestamps (utimes). The design cleanly separates directory-walk logic, tar-format encoding (delegated entirely to tar-stream), and filesystem side effects, so the core abstraction that everything else depends on is tar-stream’s pack/extract stream contract — a change there would ripple through both directions of this module.

Tech Stack Plain JavaScript (CommonJS, no build step, no TypeScript), published as a single index.js file. Runtime dependencies are tar-stream (the tar format codec this module wraps) and pump (for robust piped-stream error propagation and cleanup). Optional dependencies bare-fs and bare-path, wired through the package’s conditional imports map, let the same module run unmodified under the Bare JavaScript runtime in addition to Node.js. Dev tooling is minimal: brittle for tests, standard for linting (no separate config, opinionated defaults), and rimraf for test fixture cleanup. CI runs on GitHub Actions across Ubuntu, macOS, and Windows against the latest Node LTS.

Code Quality A single test/index.js file covers packing, extraction, symlink and hardlink handling, path stripping, header mapping, permission bits, and — notably — several explicit security regression tests: rejecting tarballs that encode absolute or escaping symlink/hardlink targets, refusing to extract through a pre-existing symlink, stripping setuid/setgid/sticky bits, and blocking entries that try to pack or extract outside the working directory. Error handling is consistently callback/stream-based: failures are forwarded via pack.destroy(err)/next(err) or the stream’s error event rather than thrown or swallowed. There is no static type layer (plain JS, no .d.ts shipped), but standard’s lint pass and cross-platform CI cover the gap somewhat for a project this size.

API Design The public surface is deliberately tiny — pack(dir, opts) and extract(dir, opts), both just returning streams — so getting started requires no setup beyond require('tar-fs') and a .pipe(). Option names read naturally (ignore, map, mapStream, strip, readable/writable shorthands for common permission patterns) and the README documents each with a runnable snippet. The main ergonomic cost is that everything is stream- and callback-oriented with no Promise-based wrapper, so callers used to async/await need to bridge it themselves.