basant307/AI_Governance_Project
045
1# node-tar2 3Fast and full-featured Tar for Node.js4 5The API is designed to mimic the behavior of `tar(1)` on unix systems.6If you are familiar with how tar works, most of this will hopefully be7straightforward for you. If not, then hopefully this module can teach8you useful unix skills that may come in handy someday :)9 10## Security Information11 12Significant efforts have been taken to harden this library13against a wide variety of filesystem based attacks, especially as14it is used to unpack packages that are published by unknown15agents to [the npm registry](https://npmjs.com/).16 17A brief overview of some of the hardening that has gone into this18implementation. (Note that most of these are disabled if19`preservePaths: true` is set in the options.)20 21- Paths that attempt to walk up outside of the extraction target22 are ignored, and a warning is raised.23- `Link` and `SymbolicLink` entries are not allowed to target24 locations outside of the extraction folder.25- Extraction is not allowed through a symbolic link that appears26 within the extraction target.27- Absolute paths are turned into relative paths underneath the28 extraction target.29- Character Device, Block Device, and FIFO entries are never30 extracted.31- File and directory ownership is not mutated unless `forceChown`32 is set, or the extraction is run as root.33- File and directory modes in the archive are ignored, unless34 the `chmod: true` option is set.35- A path-reservation system is used to ensure that even when36 multiple entries are being extracted in parallel, subsequent37 entries with the same filename will not interfere with one38 another (for example, exchanging a file with a symbolic link39 while it is being written to).40- Unicode characters in path names are fully normalized, to41 prevent evading these protections with unicode equivalences.42 43It is frankly unlikely that any tar implementation in JavaScript44is going to be as secure as this one, unless a similar amount of45work is put into it, putting it to the test over many years of46intensive use and scrutiny. You can vibe-code a tar extractor in47an afternoon, but you'll regret it.48 49> [!WARNING]50>51> **However**, all that being said, _care must still be taken_52> when dealing with data from unknown sources, especially when53> extracting files, with this or any library, no matter how54> hardened it may be. It is _your_ responsibility to use this55> library safely.56 571. **NEVER** extract tarball data into a folder that could be58 potentially controlled by an unknown actor. A clever attacker59 can swap out the target of an extracted file with a symbolic60 link to some location of their choosing, resulting in writing61 files outside the target folder. There is no reasonable way to62 harden against this category of attack, and security reports63 about it will be closed.64 [TOCTOU](https://cwe.mitre.org/data/definitions/367.html)65 exposure is unavoidable when creating files based on entries66 in an archive file.672. If you are unpacking tarballs that may come from an unknown68 source, it is **highly recommended** that you use a filter69 function that rejects all hardlinks and symbolic links. Link70 files are historically the root of nearly every file71 extraction vulnerability. (npm filters links out of package72 artifacts for this reason.)733. If you are extracting tarballs that are compressed (eg, with74 gzip, brotli, or zstd), then it is a very good idea to also75 filter out any files that are excessively large. Even if you76 are restricting the size of the archive file itself, an77 excessively large file of repetitive data can compress down78 very small, and extract to take up a lot of disk space.794. **Stay up to date.** Old versions of tar are not maintained or80 tested for newly discovered security advisories, and should be81 assumed to contain every known security vulnerability, and82 many that are unknown.83 84If you find a security vulnerability in node-tar, where it is not85properly enforcing the intended security protections, then please86report it using the GitHub Security Advisories system, where it87will be triaged and corrected if possible.88 89## Background90 91A "tar file" or "tarball" is an archive of file system entries92(directories, files, links, etc.) The name comes from "tape archive".93If you run `man tar` on almost any Unix command line, you'll learn94quite a bit about what it can do, and its history.95 96Tar has 5 main top-level commands:97 98- `c` Create an archive99- `r` Replace entries within an archive100- `u` Update entries within an archive (ie, replace if they're newer)101- `t` List out the contents of an archive102- `x` Extract an archive to disk103 104The other flags and options modify how this top level function works.105 106## High-Level API107 108These 5 functions are the high-level API. All of them have a109single-character name (for unix nerds familiar with `tar(1)`) as well110as a long name (for everyone else).111 112All the high-level functions take the following arguments, all three113of which are optional and may be omitted.114 1151. `options` - An optional object specifying various options1162. `paths` - An array of paths to add or extract1173. `callback` - Called when the command is completed, if async. (If118 sync or no file specified, providing a callback throws a119 `TypeError`.)120 121If the command is sync (ie, if `options.sync=true`), then the122callback is not allowed, since the action will be completed immediately.123 124If a `file` argument is specified, and the command is async, then a125`Promise` is returned. In this case, if async, a callback may be126provided which is called when the command is completed.127 128If a `file` option is not specified, then a stream is returned. For129`create`, this is a readable stream of the generated archive. For130`list` and `extract` this is a writable stream that an archive should131be written into. If a file is not specified, then a callback is not132allowed, because you're already getting a stream to work with.133 134`replace` and `update` only work on existing archives, and so require135a `file` argument.136 137Sync commands without a file argument return a stream that acts on its138input immediately in the same tick. For readable streams, this means139that all of the data is immediately available by calling140`stream.read()`. For writable streams, it will be acted upon as soon141as it is provided, but this can be at any time.142 143### Warnings and Errors144 145Tar emits warnings and errors for recoverable and unrecoverable situations,146respectively. In many cases, a warning only affects a single entry in an147archive, or is simply informing you that it's modifying an entry to comply148with the settings provided.149 150Unrecoverable warnings will always raise an error (ie, emit `'error'` on151streaming actions, throw for non-streaming sync actions, reject the152returned Promise for non-streaming async operations, or call a provided153callback with an `Error` as the first argument). Recoverable errors will154raise an error only if `strict: true` is set in the options.155 156Respond to (recoverable) warnings by listening to the `warn` event.157Handlers receive 3 arguments:158 159- `code` String. One of the error codes below. This may not match160 `data.code`, which preserves the original error code from fs and zlib.161- `message` String. More details about the error.162- `data` Metadata about the error. An `Error` object for errors raised by163 fs and zlib. All fields are attached to errors raisd by tar. Typically164 contains the following fields, as relevant:165 - `tarCode` The tar error code.166 - `code` Either the tar error code, or the error code set by the167 underlying system.168 - `file` The archive file being read or written.169 - `cwd` Working directory for creation and extraction operations.170 - `entry` The entry object (if it could be created) for `TAR_ENTRY_INFO`,171 `TAR_ENTRY_INVALID`, and `TAR_ENTRY_ERROR` warnings.172 - `header` The header object (if it could be created, and the entry could173 not be created) for `TAR_ENTRY_INFO` and `TAR_ENTRY_INVALID` warnings.174 - `recoverable` Boolean. If `false`, then the warning will emit an175 `error`, even in non-strict mode.176 177#### Error Codes178 179- `TAR_ENTRY_INFO` An informative error indicating that an entry is being180 modified, but otherwise processed normally. For example, removing `/` or181 `C:\` from absolute paths if `preservePaths` is not set.182 183- `TAR_ENTRY_INVALID` An indication that a given entry is not a valid tar184 archive entry, and will be skipped. This occurs when:185 - a checksum fails,186 - a `linkpath` is missing for a link type, or187 - a `linkpath` is provided for a non-link type.188 189 If every entry in a parsed archive raises an `TAR_ENTRY_INVALID` error,190 then the archive is presumed to be unrecoverably broken, and191 `TAR_BAD_ARCHIVE` will be raised.192 193- `TAR_ENTRY_ERROR` The entry appears to be a valid tar archive entry, but194 encountered an error which prevented it from being unpacked. This occurs195 when:196 - an unrecoverable fs error happens during unpacking,197 - an entry is trying to extract into an excessively deep198 location (by default, limited to 1024 subfolders),199 - an entry has `..` in the path and `preservePaths` is not set, or200 - an entry is extracting through a symbolic link, when `preservePaths` is201 not set.202 203- `TAR_ENTRY_UNSUPPORTED` An indication that a given entry is204 a valid archive entry, but of a type that is unsupported, and so will be205 skipped in archive creation or extracting.206 207- `TAR_ABORT` When parsing gzipped-encoded archives, the parser will208 abort the parse process raise a warning for any zlib errors encountered.209 Aborts are considered unrecoverable for both parsing and unpacking.210 211- `TAR_BAD_ARCHIVE` The archive file is totally hosed. This can happen for212 a number of reasons, and always occurs at the end of a parse or extract:213 - An entry body was truncated before seeing the full number of bytes.214 - The archive contained only invalid entries, indicating that it is215 likely not an archive, or at least, not an archive this library can216 parse.217 218 `TAR_BAD_ARCHIVE` is considered informative for parse operations, but219 unrecoverable for extraction. Note that, if encountered at the end of an220 extraction, tar WILL still have extracted as much it could from the221 archive, so there may be some garbage files to clean up.222 223Errors that occur deeper in the system (ie, either the filesystem or zlib)224will have their error codes left intact, and a `tarCode` matching one of225the above will be added to the warning metadata or the raised error object.226 227Errors generated by tar will have one of the above codes set as the228`error.code` field as well, but since errors originating in zlib or fs will229have their original codes, it's better to read `error.tarCode` if you wish230to see how tar is handling the issue.231 232### Examples233 234The API mimics the `tar(1)` command line functionality, with aliases235for more human-readable option and function names. The goal is that236if you know how to use `tar(1)` in Unix, then you know how to use237`import('tar')` in JavaScript.238 239To replicate `tar czf my-tarball.tgz files and folders`, you'd do:240 241```js242import { create } from 'tar'243create(244 {245 gzip: <true|gzip options>,246 file: 'my-tarball.tgz'247 },248 ['some', 'files', 'and', 'folders']249).then(_ => { .. tarball has been created .. })250```251 252To replicate `tar cz files and folders > my-tarball.tgz`, you'd do:253 254```js255// if you're familiar with the tar(1) cli flags, this can be nice256import * as tar from 'tar'257tar.c(258 {259 // 'z' is alias for 'gzip' option260 z: <true|gzip options>261 },262 ['some', 'files', 'and', 'folders']263).pipe(fs.createWriteStream('my-tarball.tgz'))264```265 266To replicate `tar xf my-tarball.tgz` you'd do:267 268```js269tar.x( // or `tar.extract`270 {271 // or `file:`272 f: 'my-tarball.tgz'273 }274).then(_=> { .. tarball has been dumped in cwd .. })275```276 277To replicate `cat my-tarball.tgz | tar x -C some-dir --strip=1`:278 279```js280fs.createReadStream('my-tarball.tgz').pipe(281 tar.x({282 strip: 1,283 C: 'some-dir', // alias for cwd:'some-dir', also ok284 }),285)286```287 288To replicate `tar tf my-tarball.tgz`, do this:289 290```js291tar.t({292 file: 'my-tarball.tgz',293 onReadEntry: entry => { .. do whatever with it .. }294})295```296 297For example, to just get the list of filenames from an archive:298 299```js300const getEntryFilenames = async tarballFilename => {301 const filenames = []302 await tar.t({303 file: tarballFilename,304 onReadEntry: entry => filenames.push(entry.path),305 })306 return filenames307}308```309 310To replicate `cat my-tarball.tgz | tar t` do:311 312```js313fs.createReadStream('my-tarball.tgz')314 .pipe(tar.t())315 .on('entry', entry => { .. do whatever with it .. })316```317 318To do anything synchronous, add `sync: true` to the options. Note319that sync functions don't take a callback and don't return a promise.320When the function returns, it's already done. Sync methods without a321file argument return a sync stream, which flushes immediately. But,322of course, it still won't be done until you `.end()` it.323 324```js325const getEntryFilenamesSync = tarballFilename => {326 const filenames = []327 tar.t({328 file: tarballFilename,329 onReadEntry: entry => filenames.push(entry.path),330 sync: true,331 })332 return filenames333}334```335 336To filter entries, add `filter: <function>` to the options.337Tar-creating methods call the filter with `filter(path, stat)`.338Tar-reading methods (including extraction) call the filter with339`filter(path, entry)`. The filter is called in the `this`-context of340the `Pack` or `Unpack` stream object.341 342The arguments list to `tar t` and `tar x` specify a list of filenames343to extract or list, so they're equivalent to a filter that tests if344the file is in the list.345 346For those who _aren't_ fans of tar's single-character command names:347 348```349tar.c === tar.create350tar.r === tar.replace (appends to archive, file is required)351tar.u === tar.update (appends if newer, file is required)352tar.x === tar.extract353tar.t === tar.list354```355 356Keep reading for all the command descriptions and options, as well as357the low-level API that they are built on.358 359### tar.c(options, fileList, callback) [alias: tar.create]360 361Create a tarball archive.362 363The `fileList` is an array of paths to add to the tarball. Adding a364directory also adds its children recursively.365 366An entry in `fileList` that starts with an `@` symbol is a tar archive367whose entries will be added. To add a file that starts with `@`,368prepend it with `./`.369 370The following options are supported:371 372- `file` Write the tarball archive to the specified filename. If this373 is specified, then the callback will be fired when the file has been374 written, and a promise will be returned that resolves when the file375 is written. If a filename is not specified, then a Readable Stream376 will be returned which will emit the file data. [Alias: `f`]377- `sync` Act synchronously. If this is set, then any provided file378 will be fully written after the call to `tar.c`. If this is set,379 and a file is not provided, then the resulting stream will already380 have the data ready to `read` or `emit('data')` as soon as you381 request it.382- `onwarn` A function that will get called with `(code, message, data)` for383 any warnings encountered. (See "Warnings and Errors")384- `strict` Treat warnings as crash-worthy errors. Default false.385- `cwd` The current working directory for creating the archive.386 Defaults to `process.cwd()`. [Alias: `C`]387- `prefix` A path portion to prefix onto the entries in the archive.388- `gzip` Set to any truthy value to create a gzipped archive, or an389 object with settings for `zlib.Gzip()` [Alias: `z`]390- `filter` A function that gets called with `(path, stat)` for each391 entry being added. Return `true` to add the entry to the archive,392 or `false` to omit it.393- `portable` Omit metadata that is system-specific: `ctime`, `atime`,394 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note395 that `mtime` is still included, because this is necessary for other396 time-based operations. Additionally, `mode` is set to a "reasonable397 default" for most unix systems, based on a `umask` value of `0o22`.398- `preservePaths` Allow absolute paths. By default, `/` is stripped399 from absolute paths. [Alias: `P`]400- `mode` The mode to set on the created file archive401- `noDirRecurse` Do not recursively archive the contents of402 directories. [Alias: `n`]403- `follow` Set to true to pack the targets of symbolic links. Without404 this option, symbolic links are archived as such. [Alias: `L`, `h`]405- `noPax` Suppress pax extended headers. Note that this means that406 long paths and linkpaths will be truncated, and large or negative407 numeric values may be interpreted incorrectly.408- `noMtime` Set to true to omit writing `mtime` values for entries.409 Note that this prevents using other mtime-based features like410 `tar.update` or the `keepNewer` option with the resulting tar archive.411 [Alias: `m`, `no-mtime`]412- `mtime` Set to a `Date` object to force a specific `mtime` for413 everything added to the archive. Overridden by `noMtime`.414- `onWriteEntry` Called with each `WriteEntry` or415 `WriteEntrySync` that is created in the course of writing the416 archive.417 418The following options are mostly internal, but can be modified in some419advanced use cases, such as re-using caches between runs.420 421- `linkCache` A Map object containing the device and inode value for422 any file whose nlink is > 1, to identify hard links.423- `statCache` A Map object that caches calls `lstat`.424- `readdirCache` A Map object that caches calls to `readdir`.425- `jobs` A number specifying how many concurrent jobs to run.426 Defaults to 4.427- `maxReadSize` The maximum buffer size for `fs.read()` operations.428 Defaults to 16 MB.429 430#### Using `onWriteEntry` to alter entries431 432The `onWriteEntry` function, if provided, will get a reference433to each `entry` object on its way into the archive.434 435If any fields on this entry are changed, then these changes will436be reflected in the entry that is written to the archive.437 438The return value of the function is ignored. All that matters is439the final state of the entry object. This can also be used to440track the files added to an archive, for example.441 442```js443import * as tar from 'tar'444const filesAdded = []445tar.c(446 {447 sync: true,448 file: 'lowercase-executable.tar',449 onWriteEntry(entry) {450 // initially, it's uppercase and 0o644451 console.log('adding', entry.path, entry.stat.mode.toString(8))452 // make all the paths lowercase453 entry.path = entry.path.toLowerCase()454 // make the entry executable455 entry.stat.mode = 0o755456 // in the archive, it's lowercase and 0o755457 filesAdded.push([entry.path, entry.stat.mode.toString(8)])458 },459 },460 ['./bin'],461)462console.log('added', filesAdded)463```464 465Then, if the `./bin` directory contained `SOME-BIN`, it would466show up in the archive as:467 468```469$ node create-lowercase-executable.js470adding ./bin/SOME-BIN 644471added [[ './bin/some-bin', '755' ]]472 473$ tar cvf lowercase-executable.tar474-rwxr-xr-x 0 isaacs 20 47731 Aug 14 08:56 ./bin/some-bin475```476 477with a lowercase name and a mode of `0o755`.478 479### tar.x(options, fileList, callback) [alias: tar.extract]480 481Extract a tarball archive.482 483The `fileList` is an array of paths to extract from the tarball. If484no paths are provided, then all the entries are extracted.485 486If the archive is gzipped, then tar will detect this and unzip it.487 488Note that all directories that are created will be forced to be489writable, readable, and listable by their owner, to avoid cases where490a directory prevents extraction of child entries by virtue of its491mode.492 493Most extraction errors will cause a `warn` event to be emitted. If494the `cwd` is missing, or not a directory, then the extraction will495fail completely.496 497The following options are supported:498 499- `cwd` Extract files relative to the specified directory. Defaults500 to `process.cwd()`. If provided, this must exist and must be a501 directory. [Alias: `C`]502- `file` The archive file to extract. If not specified, then a503 Writable stream is returned where the archive data should be504 written. [Alias: `f`]505- `sync` Create files and directories synchronously.506- `strict` Treat warnings as crash-worthy errors. Default false.507- `filter` A function that gets called with `(path, entry)` for each508 entry being unpacked. Return `true` to unpack the entry from the509 archive, or `false` to skip it.510- `newer` Set to true to keep the existing file on disk if it's newer511 than the file in the archive. [Alias: `keep-newer`,512 `keep-newer-files`]513- `keep` Do not overwrite existing files. In particular, if a file514 appears more than once in an archive, later copies will not515 overwrite earlier copies. [Alias: `k`, `keep-existing`]516- `preservePaths` Allow absolute paths, paths containing `..`, and517 extracting through symbolic links. By default, `/` is stripped from518 absolute paths, `..` paths are not extracted, and any file whose519 location would be modified by a symbolic link is not extracted.520 [Alias: `P`]521- `unlink` Unlink files before creating them. Without this option,522 tar overwrites existing files, which preserves existing hardlinks.523 With this option, existing hardlinks will be broken, as will any524 symlink that would affect the location of an extracted file. [Alias:525 `U`]526- `strip` Remove the specified number of leading path elements.527 Pathnames with fewer elements will be silently skipped. Note that528 the pathname is edited after applying the filter, but before529 security checks. [Alias: `strip-components`, `stripComponents`]530- `preserveOwner` If true, tar will set the `uid` and `gid` of531 extracted entries to the `uid` and `gid` fields in the archive.532 This defaults to true when run as root, and false otherwise. If533 false, then files and directories will be set with the owner and534 group of the user running the process. This is similar to `-p` in535 `tar(1)`, but ACLs and other system-specific data is never unpacked536 in this implementation, and modes are set by default already.537 [Alias: `p`]538- `uid` Set to a number to force ownership of all extracted files and539 folders, and all implicitly created directories, to be owned by the540 specified user id, regardless of the `uid` field in the archive.541 Cannot be used along with `preserveOwner`. Requires also setting a542 `gid` option.543- `gid` Set to a number to force ownership of all extracted files and544 folders, and all implicitly created directories, to be owned by the545 specified group id, regardless of the `gid` field in the archive.546 Cannot be used along with `preserveOwner`. Requires also setting a547 `uid` option.548- `noMtime` Set to true to omit writing `mtime` value for extracted549 entries. [Alias: `m`, `no-mtime`]550- `transform` Provide a function that takes an `entry` object, and551 returns a stream, or any falsey value. If a stream is provided,552 then that stream's data will be written instead of the contents of553 the archive entry. If a falsey value is provided, then the entry is554 written to disk as normal. (To exclude items from extraction, use555 the `filter` option described above.)556- `onReadEntry` A function that gets called with `(entry)` for each entry557 that passes the filter.558- `onwarn` A function that will get called with `(code, message, data)` for559 any warnings encountered. (See "Warnings and Errors")560- `chmod` Set to true to call `fs.chmod()` to ensure that the561 extracted file matches the entry mode. This may necessitate a562 call to the deprecated and thread-unsafe `process.umask()`563 method to determine the default umask value, unless a564 `processUmask` options is also provided. Otherwise tar will565 extract with whatever mode is provided, and let the process566 `umask` apply normally.567- `processUmask` Set to an explicit numeric value to avoid568 calling `process.umask()` when `chmod: true` is set.569- `maxDepth` The maximum depth of subfolders to extract into. This570 defaults to 1024. Anything deeper than the limit will raise a571 warning and skip the entry. Set to `Infinity` to remove the572 limitation.573- `maxDecompressionRatio` Defaults to 1000. The maximum ratio of574 decommpressed bytes to compressed bytes, in a compressed575 archive. Set to `Infinity` to allow explosive decompression.576 577The following options are mostly internal, but can be modified in some578advanced use cases, such as re-using caches between runs.579 580- `maxReadSize` The maximum buffer size for `fs.read()` operations.581 Defaults to 16 MB.582- `umask` Filter the modes of entries like `process.umask()`.583- `dmode` Default mode for directories584- `fmode` Default mode for files585- `maxMetaEntrySize` The maximum size of meta entries that is586 supported. Defaults to 1 MB.587 588Note that using an asynchronous stream type with the `transform`589option will cause undefined behavior in sync extractions.590[MiniPass](http://npm.im/minipass)-based streams are designed for this591use case.592 593### tar.t(options, fileList, callback) [alias: tar.list]594 595List the contents of a tarball archive.596 597The `fileList` is an array of paths to list from the tarball. If598no paths are provided, then all the entries are listed.599 600If the archive is gzipped, then tar will detect this and unzip it.601 602If the `file` option is _not_ provided, then returns an event emitter that603emits `entry` events with `tar.ReadEntry` objects. However, they don't604emit `'data'` or `'end'` events. (If you want to get actual readable605entries, use the `tar.Parser` class instead.)606 607If a `file` option _is_ provided, then the return value will be a promise608that resolves when the file has been fully traversed in async mode, or609`undefined` if `sync: true` is set. Thus, you _must_ specify an `onReadEntry`610method in order to do anything useful with the data it parses.611 612The following options are supported:613 614- `file` The archive file to list. If not specified, then a615 Writable stream is returned where the archive data should be616 written. [Alias: `f`]617- `sync` Read the specified file synchronously. (This has no effect618 when a file option isn't specified, because entries are emitted as619 fast as they are parsed from the stream anyway.)620- `strict` Treat warnings as crash-worthy errors. Default false.621- `filter` A function that gets called with `(path, entry)` for each622 entry being listed. Return `true` to emit the entry from the623 archive, or `false` to skip it.624- `onReadEntry` A function that gets called with `(entry)` for each entry625 that passes the filter. This is important for when `file` is set,626 because there is no other way to do anything useful with this method.627- `maxReadSize` The maximum buffer size for `fs.read()` operations.628 Defaults to 16 MB.629- `noResume` By default, `entry` streams are resumed immediately after630 the call to `onReadEntry`. Set `noResume: true` to suppress this631 behavior. Note that by opting into this, the stream will never632 complete until the entry data is consumed.633- `onwarn` A function that will get called with `(code, message, data)` for634 any warnings encountered. (See "Warnings and Errors")635- `maxDecompressionRatio` Defaults to 1000. The maximum ratio of636 decommpressed bytes to compressed bytes, in a compressed637 archive. Set to `Infinity` to allow explosive decompression.638 639### tar.u(options, fileList, callback) [alias: tar.update]640 641Add files to an archive if they are newer than the entry already in642the tarball archive.643 644The `fileList` is an array of paths to add to the tarball. Adding a645directory also adds its children recursively.646 647An entry in `fileList` that starts with an `@` symbol is a tar archive648whose entries will be added. To add a file that starts with `@`,649prepend it with `./`.650 651The following options are supported:652 653- `file` Required. Write the tarball archive to the specified654 filename. [Alias: `f`]655- `sync` Act synchronously. If this is set, then any provided file656 will be fully written after the call to `tar.c`.657- `onwarn` A function that will get called with `(code, message, data)` for658 any warnings encountered. (See "Warnings and Errors")659- `strict` Treat warnings as crash-worthy errors. Default false.660- `cwd` The current working directory for adding entries to the661 archive. Defaults to `process.cwd()`. [Alias: `C`]662- `prefix` A path portion to prefix onto the entries in the archive.663- `gzip` Set to any truthy value to create a gzipped archive, or an664 object with settings for `zlib.Gzip()` [Alias: `z`]665- `filter` A function that gets called with `(path, stat)` for each666 entry being added. Return `true` to add the entry to the archive,667 or `false` to omit it.668- `portable` Omit metadata that is system-specific: `ctime`, `atime`,669 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note670 that `mtime` is still included, because this is necessary for other671 time-based operations. Additionally, `mode` is set to a "reasonable672 default" for most unix systems, based on a `umask` value of `0o22`.673- `preservePaths` Allow absolute paths. By default, `/` is stripped674 from absolute paths. [Alias: `P`]675- `maxReadSize` The maximum buffer size for `fs.read()` operations.676 Defaults to 16 MB.677- `noDirRecurse` Do not recursively archive the contents of678 directories. [Alias: `n`]679- `follow` Set to true to pack the targets of symbolic links. Without680 this option, symbolic links are archived as such. [Alias: `L`, `h`]681- `noPax` Suppress pax extended headers. Note that this means that682 long paths and linkpaths will be truncated, and large or negative683 numeric values may be interpreted incorrectly.684- `noMtime` Set to true to omit writing `mtime` values for entries.685 Note that this prevents using other mtime-based features like686 `tar.update` or the `keepNewer` option with the resulting tar archive.687 [Alias: `m`, `no-mtime`]688- `mtime` Set to a `Date` object to force a specific `mtime` for689 everything added to the archive. Overridden by `noMtime`.690- `onWriteEntry` Called with each `WriteEntry` or691 `WriteEntrySync` that is created in the course of writing the692 archive.693 694### tar.r(options, fileList, callback) [alias: tar.replace]695 696Add files to an existing archive. Because later entries override697earlier entries, this effectively replaces any existing entries.698 699The `fileList` is an array of paths to add to the tarball. Adding a700directory also adds its children recursively.701 702An entry in `fileList` that starts with an `@` symbol is a tar archive703whose entries will be added. To add a file that starts with `@`,704prepend it with `./`.705 706The following options are supported:707 708- `file` Required. Write the tarball archive to the specified709 filename. [Alias: `f`]710- `sync` Act synchronously. If this is set, then any provided file711 will be fully written after the call to `tar.c`.712- `onwarn` A function that will get called with `(code, message, data)` for713 any warnings encountered. (See "Warnings and Errors")714- `strict` Treat warnings as crash-worthy errors. Default false.715- `cwd` The current working directory for adding entries to the716 archive. Defaults to `process.cwd()`. [Alias: `C`]717- `prefix` A path portion to prefix onto the entries in the archive.718- `gzip` Set to any truthy value to create a gzipped archive, or an719 object with settings for `zlib.Gzip()` [Alias: `z`]720- `filter` A function that gets called with `(path, stat)` for each721 entry being added. Return `true` to add the entry to the archive,722 or `false` to omit it.723- `portable` Omit metadata that is system-specific: `ctime`, `atime`,724 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note725 that `mtime` is still included, because this is necessary for other726 time-based operations. Additionally, `mode` is set to a "reasonable727 default" for most unix systems, based on a `umask` value of `0o22`.728- `preservePaths` Allow absolute paths. By default, `/` is stripped729 from absolute paths. [Alias: `P`]730- `maxReadSize` The maximum buffer size for `fs.read()` operations.731 Defaults to 16 MB.732- `noDirRecurse` Do not recursively archive the contents of733 directories. [Alias: `n`]734- `follow` Set to true to pack the targets of symbolic links. Without735 this option, symbolic links are archived as such. [Alias: `L`, `h`]736- `noPax` Suppress pax extended headers. Note that this means that737 long paths and linkpaths will be truncated, and large or negative738 numeric values may be interpreted incorrectly.739- `noMtime` Set to true to omit writing `mtime` values for entries.740 Note that this prevents using other mtime-based features like741 `tar.update` or the `keepNewer` option with the resulting tar archive.742 [Alias: `m`, `no-mtime`]743- `mtime` Set to a `Date` object to force a specific `mtime` for744 everything added to the archive. Overridden by `noMtime`.745- `onWriteEntry` Called with each `WriteEntry` or746 `WriteEntrySync` that is created in the course of writing the747 archive.748 749## Low-Level API750 751### class Pack752 753A readable tar stream.754 755Has all the standard readable stream interface stuff. `'data'` and756`'end'` events, `read()` method, `pause()` and `resume()`, etc.757 758#### constructor(options)759 760The following options are supported:761 762- `onwarn` A function that will get called with `(code, message, data)` for763 any warnings encountered. (See "Warnings and Errors")764- `strict` Treat warnings as crash-worthy errors. Default false.765- `cwd` The current working directory for creating the archive.766 Defaults to `process.cwd()`.767- `prefix` A path portion to prefix onto the entries in the archive.768- `gzip` Set to any truthy value to create a gzipped archive, or an769 object with settings for `zlib.Gzip()`770- `filter` A function that gets called with `(path, stat)` for each771 entry being added. Return `true` to add the entry to the archive,772 or `false` to omit it.773- `portable` Omit metadata that is system-specific: `ctime`, `atime`,774 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note775 that `mtime` is still included, because this is necessary for other776 time-based operations. Additionally, `mode` is set to a "reasonable777 default" for most unix systems, based on a `umask` value of `0o22`.778- `preservePaths` Allow absolute paths. By default, `/` is stripped779 from absolute paths.780- `linkCache` A Map object containing the device and inode value for781 any file whose nlink is > 1, to identify hard links.782- `statCache` A Map object that caches calls `lstat`.783- `readdirCache` A Map object that caches calls to `readdir`.784- `jobs` A number specifying how many concurrent jobs to run.785 Defaults to 4.786- `maxReadSize` The maximum buffer size for `fs.read()` operations.787 Defaults to 16 MB.788- `noDirRecurse` Do not recursively archive the contents of789 directories.790- `follow` Set to true to pack the targets of symbolic links. Without791 this option, symbolic links are archived as such.792- `noPax` Suppress pax extended headers. Note that this means that793 long paths and linkpaths will be truncated, and large or negative794 numeric values may be interpreted incorrectly.795- `noMtime` Set to true to omit writing `mtime` values for entries.796 Note that this prevents using other mtime-based features like797 `tar.update` or the `keepNewer` option with the resulting tar archive.798- `mtime` Set to a `Date` object to force a specific `mtime` for799 everything added to the archive. Overridden by `noMtime`.800- `onWriteEntry` Called with each `WriteEntry` or801 `WriteEntrySync` that is created in the course of writing the802 archive.803 804#### add(path)805 806Adds an entry to the archive. Returns the Pack stream.807 808#### write(path)809 810Adds an entry to the archive. Returns true if flushed.811 812#### end()813 814Finishes the archive.815 816### class PackSync817 818Synchronous version of `Pack`.819 820### class Unpack821 822A writable stream that unpacks a tar archive onto the file system.823 824All the normal writable stream stuff is supported. `write()` and825`end()` methods, `'drain'` events, etc.826 827Note that all directories that are created will be forced to be828writable, readable, and listable by their owner, to avoid cases where829a directory prevents extraction of child entries by virtue of its830mode.831 832`'close'` is emitted when it's done writing stuff to the file system.833 834Most unpack errors will cause a `warn` event to be emitted. If the835`cwd` is missing, or not a directory, then an error will be emitted.836 837#### constructor(options)838 839- `cwd` Extract files relative to the specified directory. Defaults840 to `process.cwd()`. If provided, this must exist and must be a841 directory.842- `filter` A function that gets called with `(path, entry)` for each843 entry being unpacked. Return `true` to unpack the entry from the844 archive, or `false` to skip it.845- `newer` Set to true to keep the existing file on disk if it's newer846 than the file in the archive.847- `keep` Do not overwrite existing files. In particular, if a file848 appears more than once in an archive, later copies will not849 overwrite earlier copies.850- `preservePaths` Allow absolute paths, paths containing `..`, and851 extracting through symbolic links. By default, `/` is stripped from852 absolute paths, `..` paths are not extracted, and any file whose853 location would be modified by a symbolic link is not extracted.854- `unlink` Unlink files before creating them. Without this option,855 tar overwrites existing files, which preserves existing hardlinks.856 With this option, existing hardlinks will be broken, as will any857 symlink that would affect the location of an extracted file.858- `strip` Remove the specified number of leading path elements.859 Pathnames with fewer elements will be silently skipped. Note that860 the pathname is edited after applying the filter, but before861 security checks.862- `umask` Filter the modes of entries like `process.umask()`.863- `dmode` Default mode for directories864- `fmode` Default mode for files865- `maxMetaEntrySize` The maximum size of meta entries that is866 supported. Defaults to 1 MB.867- `preserveOwner` If true, tar will set the `uid` and `gid` of868 extracted entries to the `uid` and `gid` fields in the archive.869 This defaults to true when run as root, and false otherwise. If870 false, then files and directories will be set with the owner and871 group of the user running the process. This is similar to `-p` in872 `tar(1)`, but ACLs and other system-specific data is never unpacked873 in this implementation, and modes are set by default already.874- `win32` True if on a windows platform. Causes behavior where875 filenames containing `<|>?` chars are converted to876 windows-compatible values while being unpacked.877- `uid` Set to a number to force ownership of all extracted files and878 folders, and all implicitly created directories, to be owned by the879 specified user id, regardless of the `uid` field in the archive.880 Cannot be used along with `preserveOwner`. Requires also setting a881 `gid` option.882- `gid` Set to a number to force ownership of all extracted files and883 folders, and all implicitly created directories, to be owned by the884 specified group id, regardless of the `gid` field in the archive.885 Cannot be used along with `preserveOwner`. Requires also setting a886 `uid` option.887- `noMtime` Set to true to omit writing `mtime` value for extracted888 entries.889- `transform` Provide a function that takes an `entry` object, and890 returns a stream, or any falsey value. If a stream is provided,891 then that stream's data will be written instead of the contents of892 the archive entry. If a falsey value is provided, then the entry is893 written to disk as normal. (To exclude items from extraction, use894 the `filter` option described above.)895- `strict` Treat warnings as crash-worthy errors. Default false.896- `onReadEntry` A function that gets called with `(entry)` for each entry897 that passes the filter.898- `onwarn` A function that will get called with `(code, message, data)` for899 any warnings encountered. (See "Warnings and Errors")900- `chmod` Set to true to call `fs.chmod()` to ensure that the901 extracted file matches the entry mode. This may necessitate a902 call to the deprecated and thread-unsafe `process.umask()`903 method to determine the default umask value, unless a904 `processUmask` options is also provided. Otherwise tar will905 extract with whatever mode is provided, and let the process906 `umask` apply normally.907- `processUmask` Set to an explicit numeric value to avoid908 calling `process.umask()` when `chmod: true` is set.909- `maxDepth` The maximum depth of subfolders to extract into. This910 defaults to 1024. Anything deeper than the limit will raise a911 warning and skip the entry. Set to `Infinity` to remove the912 limitation.913- `maxDecompressionRatio` Defaults to 1000. The maximum ratio of914 decommpressed bytes to compressed bytes, in a compressed915 archive. Set to `Infinity` to allow explosive decompression.916 917### class UnpackSync918 919Synchronous version of `Unpack`.920 921Note that using an asynchronous stream type with the `transform`922option will cause undefined behavior in sync unpack streams.923[MiniPass](http://npm.im/minipass)-based streams are designed for this924use case.925 926### class tar.Parser927 928A writable stream that parses a tar archive stream. All the standard929writable stream stuff is supported.930 931If the archive is gzipped, then tar will detect this and unzip it.932 933Emits `'entry'` events with `tar.ReadEntry` objects, which are934themselves readable streams that you can pipe wherever.935 936Each `entry` will not emit until the one before it is flushed through,937so make sure to either consume the data (with `on('data', ...)` or938`.pipe(...)`) or throw it away with `.resume()` to keep the stream939flowing.940 941#### constructor(options)942 943Returns an event emitter that emits `entry` events with944`tar.ReadEntry` objects.945 946The following options are supported:947 948- `strict` Treat warnings as crash-worthy errors. Default false.949- `filter` A function that gets called with `(path, entry)` for each950 entry being listed. Return `true` to emit the entry from the951 archive, or `false` to skip it.952- `onReadEntry` A function that gets called with `(entry)` for each entry953 that passes the filter.954- `onwarn` A function that will get called with `(code, message, data)` for955 any warnings encountered. (See "Warnings and Errors")956 957#### abort(error)958 959Stop all parsing activities. This is called when there are zlib960errors. It also emits an unrecoverable warning with the error provided.961 962### class tar.ReadEntry extends [MiniPass](http://npm.im/minipass)963 964A representation of an entry that is being read out of a tar archive.965 966It has the following fields:967 968- `extended` The extended metadata object provided to the constructor.969- `globalExtended` The global extended metadata object provided to the970 constructor.971- `remain` The number of bytes remaining to be written into the972 stream.973- `blockRemain` The number of 512-byte blocks remaining to be written974 into the stream.975- `ignore` Whether this entry should be ignored.976- `meta` True if this represents metadata about the next entry, false977 if it represents a filesystem object.978- All the fields from the header, extended header, and global extended979 header are added to the ReadEntry object. So it has `path`, `type`,980 `size`, `mode`, and so on.981 982#### constructor(header, extended, globalExtended)983 984Create a new ReadEntry object with the specified header, extended985header, and global extended header values.986 987### class tar.WriteEntry extends [MiniPass](http://npm.im/minipass)988 989A representation of an entry that is being written from the file990system into a tar archive.991 992Emits data for the Header, and for the Pax Extended Header if one is993required, as well as any body data.994 995Creating a WriteEntry for a directory does not also create996WriteEntry objects for all of the directory contents.997 998It has the following fields:999 1000- `path` The path field that will be written to the archive. By1001 default, this is also the path from the cwd to the file system1002 object.1003- `portable` Omit metadata that is system-specific: `ctime`, `atime`,1004 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note1005 that `mtime` is still included, because this is necessary for other1006 time-based operations. Additionally, `mode` is set to a "reasonable1007 default" for most unix systems, based on a `umask` value of `0o22`.1008- `myuid` If supported, the uid of the user running the current1009 process.1010- `myuser` The `env.USER` string if set, or `''`. Set as the entry1011 `uname` field if the file's `uid` matches `this.myuid`.1012- `maxReadSize` The maximum buffer size for `fs.read()` operations.1013 Defaults to 1 MB.1014- `linkCache` A Map object containing the device and inode value for1015 any file whose nlink is > 1, to identify hard links.1016- `statCache` A Map object that caches calls `lstat`.1017- `preservePaths` Allow absolute paths. By default, `/` is stripped1018 from absolute paths.1019- `cwd` The current working directory for creating the archive.1020 Defaults to `process.cwd()`.1021- `absolute` The absolute path to the entry on the filesystem. By1022 default, this is `path.resolve(this.cwd, this.path)`, but it can be1023 overridden explicitly.1024- `strict` Treat warnings as crash-worthy errors. Default false.1025- `win32` True if on a windows platform. Causes behavior where paths1026 replace `\` with `/` and filenames containing the windows-compatible1027 forms of `<|>?:` characters are converted to actual `<|>?:` characters1028 in the archive.1029- `noPax` Suppress pax extended headers. Note that this means that1030 long paths and linkpaths will be truncated, and large or negative1031 numeric values may be interpreted incorrectly.1032- `noMtime` Set to true to omit writing `mtime` values for entries.1033 Note that this prevents using other mtime-based features like1034 `tar.update` or the `keepNewer` option with the resulting tar archive.1035 1036#### constructor(path, options)1037 1038`path` is the path of the entry as it is written in the archive.1039 1040The following options are supported:1041 1042- `portable` Omit metadata that is system-specific: `ctime`, `atime`,1043 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note1044 that `mtime` is still included, because this is necessary for other1045 time-based operations. Additionally, `mode` is set to a "reasonable1046 default" for most unix systems, based on a `umask` value of `0o22`.1047- `maxReadSize` The maximum buffer size for `fs.read()` operations.1048 Defaults to 1 MB.1049- `linkCache` A Map object containing the device and inode value for1050 any file whose nlink is > 1, to identify hard links.1051- `statCache` A Map object that caches calls `lstat`.1052- `preservePaths` Allow absolute paths. By default, `/` is stripped1053 from absolute paths.1054- `cwd` The current working directory for creating the archive.1055 Defaults to `process.cwd()`.1056- `absolute` The absolute path to the entry on the filesystem. By1057 default, this is `path.resolve(this.cwd, this.path)`, but it can be1058 overridden explicitly.1059- `strict` Treat warnings as crash-worthy errors. Default false.1060- `win32` True if on a windows platform. Causes behavior where paths1061 replace `\` with `/`.1062- `onwarn` A function that will get called with `(code, message, data)` for1063 any warnings encountered. (See "Warnings and Errors")1064- `noMtime` Set to true to omit writing `mtime` values for entries.1065 Note that this prevents using other mtime-based features like1066 `tar.update` or the `keepNewer` option with the resulting tar archive.1067- `umask` Set to restrict the modes on the entries in the archive,1068 somewhat like how umask works on file creation. Defaults to1069 `process.umask()` on unix systems, or `0o22` on Windows.1070 1071#### warn(message, data)1072 1073If strict, emit an error with the provided message.1074 1075Otherwise, emit a `'warn'` event with the provided message and data.1076 1077### class tar.WriteEntry.Sync1078 1079Synchronous version of tar.WriteEntry1080 1081### class tar.WriteEntry.Tar1082 1083A version of tar.WriteEntry that gets its data from a tar.ReadEntry1084instead of from the filesystem.1085 1086#### constructor(readEntry, options)1087 1088`readEntry` is the entry being read out of another archive.1089 1090The following options are supported:1091 1092- `portable` Omit metadata that is system-specific: `ctime`, `atime`,1093 `uid`, `gid`, `uname`, `gname`, `dev`, `ino`, and `nlink`. Note1094 that `mtime` is still included, because this is necessary for other1095 time-based operations. Additionally, `mode` is set to a "reasonable1096 default" for most unix systems, based on a `umask` value of `0o22`.1097- `preservePaths` Allow absolute paths. By default, `/` is stripped1098 from absolute paths.1099- `strict` Treat warnings as crash-worthy errors. Default false.1100- `onwarn` A function that will get called with `(code, message, data)` for1101 any warnings encountered. (See "Warnings and Errors")1102- `noMtime` Set to true to omit writing `mtime` values for entries.1103 Note that this prevents using other mtime-based features like1104 `tar.update` or the `keepNewer` option with the resulting tar archive.1105 1106### class tar.Header1107 1108A class for reading and writing header blocks.1109 1110It has the following fields:1111 1112- `nullBlock` True if decoding a block which is entirely composed of1113 `0x00` null bytes. (Useful because tar files are terminated by1114 at least 2 null blocks.)1115- `cksumValid` True if the checksum in the header is valid, false1116 otherwise.1117- `needPax` True if the values, as encoded, will require a Pax1118 extended header.1119- `path` The path of the entry.1120- `mode` The 4 lowest-order octal digits of the file mode. That is,1121 read/write/execute permissions for world, group, and owner, and the1122 setuid, setgid, and sticky bits.1123- `uid` Numeric user id of the file owner1124- `gid` Numeric group id of the file owner1125- `size` Size of the file in bytes1126- `mtime` Modified time of the file1127- `cksum` The checksum of the header. This is generated by adding all1128 the bytes of the header block, treating the checksum field itself as1129 all ascii space characters (that is, `0x20`).1130- `type` The human-readable name of the type of entry this represents,1131 or the alphanumeric key if unknown.1132- `typeKey` The alphanumeric key for the type of entry this header1133 represents.1134- `linkpath` The target of Link and SymbolicLink entries.1135- `uname` Human-readable user name of the file owner1136- `gname` Human-readable group name of the file owner1137- `devmaj` The major portion of the device number. Always `0` for1138 files, directories, and links.1139- `devmin` The minor portion of the device number. Always `0` for1140 files, directories, and links.1141- `atime` File access time.1142- `ctime` File change time.1143 1144#### constructor(data, [offset=0])1145 1146`data` is optional. It is either a Buffer that should be interpreted1147as a tar Header starting at the specified offset and continuing for1148512 bytes, or a data object of keys and values to set on the header1149object, and eventually encode as a tar Header.1150 1151#### decode(block, offset)1152 1153Decode the provided buffer starting at the specified offset.1154 1155Buffer length must be greater than 512 bytes.1156 1157#### set(data)1158 1159Set the fields in the data object.1160 1161#### encode(buffer, offset)1162 1163Encode the header fields into the buffer at the specified offset.1164 1165Returns `this.needPax` to indicate whether a Pax Extended Header is1166required to properly encode the specified data.1167 1168### class tar.Pax1169 1170An object representing a set of key-value pairs in an Pax extended1171header entry.1172 1173It has the following fields. Where the same name is used, they have1174the same semantics as the tar.Header field of the same name.1175 1176- `global` True if this represents a global extended header, or false1177 if it is for a single entry.1178- `atime`1179- `charset`1180- `comment`1181- `ctime`1182- `gid`1183- `gname`1184- `linkpath`1185- `mtime`1186- `path`1187- `size`1188- `uid`1189- `uname`1190- `dev`1191- `ino`1192- `nlink`1193 1194#### constructor(object, global)1195 1196Set the fields set in the object. `global` is a boolean that defaults1197to false.1198 1199#### encode()1200