npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

exarch-rs

v0.11.0

Published

Memory-safe archive extraction library with built-in security validation

Readme

exarch-rs

npm Node TypeScript CI License

Memory-safe archive extraction and creation library for Node.js.

Important: exarch is designed as a secure replacement for vulnerable archive libraries like tar-fs, which has known CVEs with CVSS scores up to 9.4.

This package provides Node.js bindings for exarch-core, a Rust library with built-in protection against common archive vulnerabilities.

Installation

# npm
npm install exarch-rs

# yarn
yarn add exarch-rs

# pnpm
pnpm add exarch-rs

# bun
bun add exarch-rs

Note: This package includes TypeScript definitions. No need for a separate @types package.

Requirements

  • Node.js >= 20

Runtime support

Node.js is the fully supported runtime, exercised by the complete test matrix. Bun and Deno are smoke-tested in CI (basic create/list/verify/extract plus the progress callback and a security-violation error path) but are not part of the full Node.js test matrix. The smoke test does not exercise a Rust panic crossing the addon boundary, so catch_unwind behavior under Bun/Deno is unverified.

Quick Start

Extraction

const { extractArchive } = require('exarch-rs');

// Async (recommended)
const result = await extractArchive('archive.tar.gz', '/output/path');
console.log(`Extracted ${result.filesExtracted} files`);

Creation

const { createArchive } = require('exarch-rs');

// Async (recommended)
const result = await createArchive('backup.tar.gz', ['src/', 'package.json']);
console.log(`Created archive with ${result.filesAdded} files`);

Usage

Async API (Recommended)

const { extractArchive } = require('exarch-rs');

const result = await extractArchive('archive.tar.gz', '/output/path');

console.log(`Files extracted: ${result.filesExtracted}`);
console.log(`Bytes written: ${result.bytesWritten}`);
console.log(`Duration: ${result.durationMs}ms`);

Sync API

const { extractArchiveSync } = require('exarch-rs');

const result = extractArchiveSync('archive.tar.gz', '/output/path');
console.log(`Extracted ${result.filesExtracted} files`);

Tip: Prefer the async API to avoid blocking the event loop during extraction.

ES Modules

import { extractArchive } from 'exarch-rs';

const result = await extractArchive('archive.tar.gz', '/output/path');

TypeScript

import { extractArchive, SecurityConfig, ExtractionReport } from 'exarch-rs';

const result: ExtractionReport = await extractArchive('archive.tar.gz', '/output/path');
console.log(`Extracted ${result.filesExtracted} files`);

Custom Security Configuration

import { extractArchive, SecurityConfig } from 'exarch-rs';

const config = new SecurityConfig()
  .withMaxFileSize(100 * 1024 * 1024)   // 100 MB per file
  .withMaxTotalSize(1024 * 1024 * 1024) // 1 GB total
  .withMaxFileCount(10_000);             // Max 10k entries

const result = await extractArchive('archive.tar.gz', '/output', config);

Verifying Payload Integrity

verifyArchive checks security only by default and reports integrityStatus as 'SKIPPED'. Opt in to decode the payload and verify checksums:

const { verifyArchive, VerificationOptions } = require('exarch-rs');

const options = new VerificationOptions().withIntegrityCheck(); // 500 MiB budget
const report = await verifyArchive('archive.zip', null, options);

console.log(report.integrityStatus); // 'OK', 'FAILED', 'INCOMPLETE' or 'SKIPPED'

Note: 'INCOMPLETE' means part of the payload was not verified (budget, resource limit, solid 7z archive while withAllowSolidArchives is off, TAR without an end-of-archive marker); it comes with a Medium issue, so status is at least 'WARNING'. With the check on, a TAR entry whose content fails to decode rejects the promise.

Password-Protected Archives

ZIP archives with WinZip AES and 7z archives with AES-256 are read when you pass a Uint8Array (a Buffer works) as the password argument of extractArchive, extractArchiveSync, extractArchiveWithProgress, listArchive, listArchiveSync, verifyArchive, verifyArchiveSync, the listArchiveBytes and verifyArchiveBytes families (also the WithProgress and Sync forms; last parameter, after signal or progress), extractArchiveToMemory[WithProgress][Sync] or extractArchiveToCallback[Sync] (the last parameter, after signal). A string is refused because it cannot be wiped; exarch wipes its own copy and you wipe yours.

const { extractArchiveSync } = require('exarch');

const password = Buffer.from('correct-horse');
try {
  extractArchiveSync('secret.zip', 'out', null, null, password);
} finally {
  password.fill(0); // best effort: wipe your copy
}

A missing, wrong or weak (ZipCrypto) password throws a SECURITY_VIOLATION error with subCode === 'ENCRYPTED'; a password for an archive that is not encrypted is ignored; a 7z password that is not UTF-8 text throws it with reason === 'unusable_password'. encrypted on a listed entry tells whether its data is encrypted, with or without a password. SecurityConfig.maxKdfWork bounds the key-derivation work of one 7z operation. Zeroization across the binding boundary is best effort.

Key-derivation budget. max_kdf_work bounds the key-derivation work that a 7z operation requests.

Archives in Memory

listArchiveBytes, verifyArchiveBytes and extractArchiveToMemory (each with a Sync form) take the archive as a Buffer or Uint8Array. The format is detected from the leading bytes, or stated with format ('Tar', 'TarGz', 'TarBz2', 'TarXz', 'TarZst', 'Zip', 'SevenZ'). Nothing is written to disk.

const fs = require('node:fs');
const { listArchiveBytes, verifyArchiveBytes, extractArchiveToMemory } = require('exarch-rs');

const data = fs.readFileSync('archive.tar.gz');

const manifest = await listArchiveBytes(data);
const report = await verifyArchiveBytes(data);

const result = await extractArchiveToMemory(data, null, null, 64 * 1024 * 1024);
for (const entry of result.entries) {
  console.log(entry.path, entry.kind); // 'file', 'directory' or 'symlink'; 'hardlink' only from extractArchiveToCallback
  if (entry.kind === 'file') {
    const content = Buffer.from(entry.data); // entry.data is a Uint8Array
  }
}

MemoryEntry is a union discriminated by kind: a file always has data, a symlink or hardlink always has target. The in-memory and callback functions take SinkOptions (withExistingFiles, withDecodeReuse) as options, not ExtractionOptions: a sink has no directory to rename, so staging cannot be requested.

Note: maxBytes caps payload plus path bytes plus 256 per entry and defaults to the config's maxTotalSize; exceeding it rejects with QUOTA_EXCEEDED. pathModel: 'portable' validates names against the strictest rules of every platform instead of this host's.

Every in-memory function takes its arguments in one order: the data, config, options, the function's own arguments (maxBytes, pathModel), format, progress, signal. listArchiveBytes(data, config?, options?, format?, signal?) is one example.

listArchiveBytesWithProgress, verifyArchiveBytesWithProgress and extractArchiveToMemoryWithProgress (async only) take a progress callback after format (and before the optional signal), called with (err, [path, total, current, bytesWritten]); current counts from 1 and total is null while the entry count is unknown (a TAR stream). A throwing callback stops the run before the next entry, and the promise rejects with PROGRESS_CALLBACK_ERROR and the result is discarded.

The async forms of these functions (and of their WithProgress variants) also take an AsyncIterable<Uint8Array> as the archive, for example fs.createReadStream(path) or an HTTP response body. It must be a TAR family format (plain or compressed). It is read from a worker thread, one chunk at a time, and closed (return()) however the call ends, so a refused archive does not leave the stream open. A throwing or rejecting stream rejects with STREAM_ERROR and the thrown value as cause. The sync functions take bytes only. A stream that never yields keeps the call pending, and an onEntry promise that never settles does the same, unless the call is given an AbortSignal (below); there is no timeout. Each in-flight stream or onEntry call pins a thread of the blocking pool for the whole call, so many slow streams (for example HTTP bodies) can exhaust the pool and stall every other async exarch call in the process.

These seven async functions (listArchiveBytes, verifyArchiveBytes, extractArchiveToMemory, extractArchiveToCallback and the WithProgress variants of the first three) take an optional signal?: AbortSignal as their last argument. Aborting rejects the promise with code === 'ABORT_ERR', name === 'AbortError' and cause set to signal.reason, frees the worker thread and queues the close of the stream without waiting for it. A signal that is already aborted rejects without opening the archive. The abort is noticed at the start of the job, while it waits for JavaScript (the next chunk of an AsyncIterable, the close of the iterable, and the promise an onEntry call returned, which is abandoned, not cancelled), at every read of a Uint8Array archive, and at every progress callback of the WithProgress variants, which stop being called once the signal fired. The work between two reads of a Uint8Array is not interrupted, and a call whose last read has happened resolves normally. A value that is not an AbortSignal (any object with aborted and addEventListener is accepted, including a signal from another realm) throws a TypeError synchronously.

extractArchiveToCallback(data, onEntry, config?, options?, pathModel?, format?, signal?) hands each verified entry to onEntry(entry) instead of collecting them, so memory use is one file at a time (bounded by maxFileSize). A file arrives whole, after its size was verified. Entries are provisional: each is delivered as soon as it is verified, so a later failure refuses the archive after earlier entries were already delivered; treat the results as final only once the promise resolved. The gzip trailer (CRC and length) of a .tar.gz is checked once the archive has been read to its end, so a corrupt compressed stream is refused, but only after the entries before it were delivered. The extraction waits for the promise onEntry returns before it reads on, so a slow consumer applies backpressure. A throw or rejection stops the extraction and rejects with ENTRY_CALLBACK_ERROR and the thrown value as cause; a thrown primitive is wrapped in an Error whose cause is the primitive (a Symbol is stringified). A 'symlink' entry's target is spelled as the archive stores it, relative to the link. A 'hardlink' entry comes last and by reference: its target is the root-relative resolved path of an entry already delivered, a file or an earlier hardlink (a chain is delivered link by link). With existingFiles set to 'overwrite' a path can be delivered more than once and a hardlink refers to the latest delivery; implicit parent directories are not delivered.

const sizes = new Map();
await extractArchiveToCallback(fs.createReadStream('archive.tar.gz'), async (entry) => {
  if (entry.kind === 'file') sizes.set(entry.path, entry.data.length);
});

extractArchiveToCallbackSync runs onEntry on the JavaScript thread and takes bytes only, which it copies before onEntry first runs, so a callback can neither detach nor change the input under the parser. A callback that returns a promise is refused with ENTRY_CALLBACK_ERROR and a TypeError as cause (its rejection is silenced, so it cannot become an unhandled rejection); use the async function for async work.

extractArchiveToMemoryWithProgressSync, listArchiveBytesWithProgressSync and verifyArchiveBytesWithProgressSync take the progress callback last; its calls arrive only after the function has returned, and a throw there is an uncaughtException.

createArchiveToBytes(sources, format) (and createArchiveToBytesSync) builds an archive in memory and resolves to { data, report }:

const { data, report } = await createArchiveToBytes(['src/'], 'TarGz');

Note: the whole archive is held in memory, up to about 2-3x its size at the peak, and there is no size cap. Sources must be regular files and directories; FIFOs and device files are not supported. Use createArchive for large archives.

Error Handling

const { extractArchive } = require('exarch-rs');

try {
  const result = await extractArchive('archive.tar.gz', '/output');
  console.log(`Success: ${result.filesExtracted} files`);
} catch (error) {
  // error.code: PATH_TRAVERSAL, SYMLINK_ESCAPE, ZIP_BOMB, QUOTA_EXCEEDED, etc.
  if (error.code === 'QUOTA_EXCEEDED' && error.writes === 'kept') {
    console.error(`Partial extraction left ${error.filesExtracted} files on disk`);
  }
  console.error(`Extraction failed: ${error.message}`);
}

error.message is the human-readable description only. The generated index.d.ts names AsyncIterable and carries a lib="es2018.asynciterable" reference. Everything machine-readable is a property, typed as ExarchError in index.d.ts: a union you can narrow on writes, whose code is an ErrorCode for every member except ExarchNativeError. Cast to ExarchCoreError (every member but the native one) to narrow on code: 'INVALID_ARCHIVE' pairs with InvalidArchiveSubCode, 'SECURITY_VIOLATION' with a required SecurityViolationSubCode, 'IO_ERROR' with a required ioKind, so code === 'PATH_TRAVERSAL' && subCode === 'INTEGRITY' does not type-check.

| Property | Set when | Value | |----------|----------|-------| | code | always | An ErrorCode such as 'PATH_TRAVERSAL', 'QUOTA_EXCEEDED' or 'SECURITY_VIOLATION'. A path rejected at the boundary (null byte, too long) is 'SECURITY_VIOLATION' and a rejected setter value (a zero or negative limit, a non-positive ratio, an unusable list entry) is 'INVALID_CONFIGURATION' with a setting naming it. Errors raised by the binding itself (an internal panic, a failed argument conversion) are ExarchNativeError: code is napi's status string ('GenericFailure', 'InvalidArg', ...), not an ErrorCode, and no other property is set. | | relaxableBy | a SECURITY_VIOLATION that a SecurityConfig setting would admit | The PolicySetting id, for example 'symlinks' | | subCode | an INVALID_ARCHIVE with a finer classification, every core SECURITY_VIOLATION, every QUOTA_EXCEEDED and every ZIP_BOMB | on INVALID_ARCHIVE, 'TAR_AMBIGUITY' (a TAR header read differently by different tools), 'TAR_TRAILER' (the stream after the TAR end-of-archive marker is corrupt or truncated), 'ZIP_READER' (a failure of the ZIP reader or of the structural check built on it), 'LINK_TARGET', 'DUPLICATE_ENTRY', 'ENTRY_NAME', 'DECLARED_SIZE', 'INTEGRITY' (the refusal of that family), 'TAR_READER' or 'SEVENZ_READER' (a failure of the TAR or 7z reader); on SECURITY_VIOLATION, the family of the refusal, one of 'PATH_NAME', 'PATH_DEPTH', 'LINK_TARGET', 'LINK_POLICY', 'EXISTING_SYMLINK', 'ENTRY_TYPE', 'ROOT_ENTRY', 'ENCRYPTED', 'COMPRESSION_METHOD', 'SOLID_ARCHIVE', 'DECLARED_SIZE', 'CONCURRENT_CHANGE', 'TAR_METADATA', 'TAR_TRAILER', 'PLATFORM', 'OUTPUT_CONFLICT', 'SOURCE_PATH'; on QUOTA_EXCEEDED, the quota ('FILE_COUNT', 'TOTAL_SIZE', 'FILE_SIZE', 'INTEGER_OVERFLOW', 'DECODER_MEMORY', 'COMPRESSED_MEMBERS', 'TREE_NODES', 'SINK_CAPACITY', 'SOLID_BLOCK_MEMORY', 'HEADER_SIZE' or 'HEADER_ENTRY_COUNT'); on ZIP_BOMB, what the ratio was measured over ('ENTRY', 'SOLID_BLOCK' or 'SKIPPED_ENTRIES'); typed InvalidArchiveSubCode, SecurityViolationSubCode, QuotaSubCode or ZipBombSubCode | | nonUtf8EntryPath | an INVALID_ARCHIVE ('ENTRY_NAME') refusal of an entry name that is not valid UTF-8 | The name written injectively: a backslash is \x5C, each invalid byte \xNN | | restore, backupPath | an IO_ERROR from a failed 'atomic_replace' | restore is 'not_needed', 'restored' or 'failed'; backupPath names where the original remains after 'failed'; paths are redacted like the message | | leftoverPath | a staging directory or an empty output reservation file stayed on disk (a failed 'atomic_replace', a rolled-back extraction, a creation that left its reservation) | The leftover, redacted like the message | | path | a SOURCE_NOT_FOUND, a SOURCE_CHANGED, an OUTPUT_EXISTS, or an IO_ERROR that left an empty output reservation | The source, the existing output or destination, or the reservation file, redacted like the message | | conflicts, by | an OUTPUT_EXISTS from a 'refuse' extraction, or an extraction that met a directory occupant | conflicts is a list of { path, occupant? } with the kind of occupant; by says who made it ('existing' or 'archive') and is also set on an EXISTING_SYMLINK security violation | | protectedPath, collision, unmatchedPatterns | an INVALID_CONFIGURATION for a protected 'atomic_replace' destination, for creation sources that map to one entry name, or for include patterns that matched no entry | 'filesystem_root', 'archive_ancestor' or 'working_directory'; { name, first, second }; the unmatched patterns | | ioKind | an IO_ERROR | The IoKind core reported, for example 'NotFound', 'PermissionDenied' or 'StorageFull'; 'Other' for a kind with no entry in IoKind | | writes | an extraction failed after producing output | 'kept', 'rolled_back' (atomic extraction discarded the output) or 'discarded' (an in-memory extraction wrote nothing to disk and dropped its entries) | | filesExtracted, bytesWritten, filesSkipped, skipped, warnings | writes === 'kept' | Counters, the skips by reason and the typed ExtractionWarning[] | | errno, strerror, path | a SOURCE_NOT_ACCESSIBLE | The OS error number (when the failure has one), its text and the unreadable source, redacted like the message | | cause | a progress callback, an onEntry callback or an AsyncIterable archive threw | The exception it threw (a thrown primitive is wrapped in an Error whose cause is the primitive) |

code === 'ENTRY_CALLBACK_ERROR' means an onEntry callback threw or rejected and code === 'STREAM_ERROR' that an AsyncIterable archive did; both carry no counters and take priority over the core error they caused. code === 'ABORT_ERR' (with name === 'AbortError' and cause set to the signal's reason) means the call's AbortSignal fired; it takes priority over the errors the abort caused. code === 'CANCELLED' is a cancellation that no JavaScript signal caused. A core error other than a cancellation always stays primary over a callback throw that happened in the same run.

A progress callback that throws stops the operation before the next entry. The rejection has code === 'PROGRESS_CALLBACK_ERROR', the throw as cause, and the counters of what was written (filesExtracted... for extraction, filesAdded and bytesWritten for creation). The in-memory extraction functions write nothing, so their rejection carries writes === 'discarded' and no counters.

Breaking change: earlier versions put the code, a [relaxableBy=<id>] token and a | writes=... suffix into message. Read the properties instead.

API

extractArchive(archivePath, outputDir, config?, options?)

Extract an archive asynchronously with security validation.

Parameters:

| Name | Type | Description | |------|------|-------------| | archivePath | string | Path to the archive file | | outputDir | string | Directory where files will be extracted | | config | SecurityConfig | Optional security configuration | | options | ExtractionOptions | Optional new ExtractionOptions().withStaging('in_place' \| 'atomic' \| 'atomic_replace') / .withExistingFiles('skip' \| 'overwrite' \| 'refuse') |

Returns: Promise<ExtractionReport>

extractArchiveSync(archivePath, outputDir, config?, options?)

Synchronous version. Blocks the event loop until extraction completes.

Returns: ExtractionReport

Listing entries

listArchive returns entries as a union discriminated by entryType (ArchiveEntry): a 'File' has size, a 'Symlink' or 'Hardlink' has a target that is itself a union discriminated by state ('recorded' with a path, 'missing', 'unread', 'unreadable' or 'oversized' with bytes), and a 'Directory' has neither. mode is the raw archive mode. An entry whose name is not valid UTF-8 makes the listing fail with INVALID_ARCHIVE and subCode: 'ENTRY_NAME' rather than being rendered lossily; verification issues, integrity gaps, skip samples and progress callbacks render a path with an injective encoding instead: a backslash is \x5C and each invalid byte is \xNN, so two distinct entries never share a rendered name (the literal name a\xFFb renders as a\x5CxFFb, the name a + byte 0xFF + b as a\xFFb). Names without backslashes and invalid bytes are unchanged.

verifyArchive issues carry the typed refusal behind a finding: code, subCode, relaxableBy, setting, ioKind and mode (the raw permission bits of an invalid-permissions refusal or an executable file), paired as on an error (VerificationIssue in index.d.ts); the former context string is gone.

ExtractionReport

interface ExtractionReport {
  filesExtracted: number;     // Number of files extracted
  directoriesCreated: number; // Number of directories created
  symlinksCreated: number;    // Number of symlinks created
  bytesWritten: number;       // Total bytes written
  sizeClamped: boolean;       // bytesWritten exceeded 2^53 - 1 and was clamped to it
  durationMs: number;         // Extraction duration in milliseconds
  filesSkipped: number;       // Entries skipped, over all reasons
  skipped: { counts: { kind: SkipKind; count: number }[]; sample: SkippedEntry[]; total: number }; // by reason
  warnings: ExtractionWarning[]; // Typed conditions worth surfacing (e.g. `root_access_narrowed` with a `reason`); branch on `kind`, `message` is the text
}

Numbers. Counts (filesExtracted, totalEntries, every count and total) are exact JavaScript numbers. Byte sizes are clamped to 2^53 - 1, the largest integer a number holds exactly; an object with byte-size fields carries sizeClamped: true when any of them was clamped, so an absurd declared size is never mistaken for a real value of 9007199254740991. The Python binding reports exact integers and has no such flag.

Counts shape. skipped.counts and integrityGaps.counts are arrays of { kind | reason, count } in a fixed order, with reasons that have no items left out. The Python binding exposes the same data as a dict keyed by the reason; both give total.

Tokens newer than the binding. Fields that name a core enum value (kind, reason, ioKind, format, integrityStatus, category, code, subCode, relaxableBy, setting) carry core's own spelling, typed as the known union widened with (string & {}). A listing, verification or extraction that succeeded in core never fails because a report field is newer than the binding. A discriminated object of an unknown kind (a warning, a disposition, a link target, an entry) degrades to an Unknown* object holding only its token; the unions stay closed so that narrowing on the discriminant keeps working.

extractArchiveWithProgress(archivePath, outputDir, config?, options?, progress?)

Async extraction with an optional progress callback, invoked once per entry.

progress uses napi's standard threadsafe-function calling convention: (err, arg), where err is always null and arg is the [path, total, current, bytesWritten] tuple — not four separate arguments. bytesWritten is always 0: the callback only fires from the entry-start event, before any bytes for that entry have been counted.

import { extractArchiveWithProgress } from 'exarch-rs';

const result = await extractArchiveWithProgress(
  'archive.tar.gz',
  '/output/path',
  undefined,  // SecurityConfig or undefined
  undefined,  // ExtractionOptions or undefined
  (err, [path, total, current, bytesWritten]) => {
    console.log(`[${current}/${total}] ${path}`);
  }
);

Parameters:

| Name | Type | Description | |------|------|-------------| | archivePath | string | Path to the archive file | | outputDir | string | Directory where files will be extracted | | config | SecurityConfig \| undefined | Optional security configuration | | options | ExtractionOptions \| undefined | Optional extraction options | | progress | (err: Error \| null, arg: ProgressArgs) => void \| undefined | Optional progress callback |

Returns: Promise<ExtractionReport>

Exclude patterns

CreationConfig.withExcludePatterns(patterns) replaces the list (the defaults included) and addExcludePattern(pattern) appends one; both accept glob patterns. * and ? match within one path component (? is exactly one byte), [a-c] is a positive ASCII class, and ** as a whole component spans directories (src/**/*.rs). A name without / (build, *.tmp) matches any path component, and so its subtree; a pattern with a / anywhere, a trailing one included (target/), matches from the archive root and its subtree. Patterns match the entry's archive path, never the ancestors of a source directory, so for a source src write build, not src/build. Unsupported syntax, such as {a,b}, !a.txt, a**b, [!x], [a, a,b, a pattern with leading or trailing whitespace, an empty one, .. or an absolute path, throws INVALID_CONFIGURATION with setting: 'exclude_pattern' instead of silently excluding nothing.

Create options

createArchive, createArchiveSync and createArchiveWithProgress take an optional trailing CreateOptions argument: { format?: CreatableFormat; overwrite?: boolean; durability?: Durability }. overwrite defaults to true: an existing output is replaced when creation succeeds, and a failed creation leaves it untouched; overwrite: false refuses an existing output with OUTPUT_EXISTS. format overrides the format the output extension names, which is how a .apk or .whl is written as a plain ZIP. CreatableFormat is ArchiveType without 'SevenZ', which cannot be created: passing it is refused at the boundary with an InvalidArg error from napi-rs, not an exarch error code. createArchiveToBytes takes a CreatableFormat as an argument and has no output file.

durability is 'synced' (the default) or 'unsynced'. 'synced' flushes the archive and its directory entry before the call succeeds. 'unsynced' skips both, which is faster, but after a crash or power loss a replaced output can be empty or truncated and a new output can be empty, and write-back errors (network filesystems, quotas, delayed allocation) are not reported, so success does not prove the bytes reached the disk.

createArchiveWithProgress(outputPath, sources, config?, options?, progress?)

Async archive creation with an optional progress callback, invoked once per entry.

progress uses the same (err, arg) calling convention as extractArchiveWithProgress above — arg is [path, total, current, bytesWritten], and bytesWritten is always 0 for the same reason.

import { createArchiveWithProgress } from 'exarch-rs';

const result = await createArchiveWithProgress(
  'backup.tar.gz',
  ['src/', 'package.json'],
  undefined,  // CreationConfig or undefined
  undefined,  // CreateOptions or undefined
  (err, [path, total, current, bytesWritten]) => {
    console.log(`[${current}/${total}] ${path}`);
  }
);

Parameters:

| Name | Type | Description | |------|------|-------------| | outputPath | string | Path to the output archive file | | sources | string[] | Source files/directories to include | | config | CreationConfig \| undefined | Optional creation configuration | | options | CreateOptions \| undefined | Optional { format, overwrite, durability } (see Create options) | | progress | (err: Error \| null, arg: ProgressArgs) => void \| undefined | Optional progress callback, last like in every *WithProgress function |

Returns: Promise<CreationReport>

SecurityConfig

Builder-style security configuration.

const config = new SecurityConfig()
  .withMaxFileSize(bytes)                     // Max size per file
  .withMaxTotalSize(bytes)                    // Max total extraction size
  .withMaxFileCount(count)                    // Max number of entries (every entry counts, directories included)
  .withMaxCompressionRatio(n)                 // Max compression ratio (zip bomb detection)
  .addAllowedExtension(".txt")               // Restrict to a set of extensions (repeatable)
  .withAllowedExtensions([".txt", ".md"])     // Replace the allowlist; null allows every extension, [] is refused
  .addBannedComponent("__MACOSX")            // Skip this path component (repeatable)
  .withBannedComponents(["__MACOSX"])         // Replace the banned components; [] bans nothing
  .addIncludePattern("src")                  // Extract only matching entries (repeatable, or withIncludePatterns([...]))
  .addExcludePattern("*.tmp")                // Never extract matching entries; wins over include (or withExcludePatterns([...]))
  .withStripComponents(1)                     // Drop leading path components, like tar --strip-components; null removes a count but keeps flatten
  .withFlatten(true)                          // Land every file under its final component (replaces a strip count)
  .withAllowSolidArchives(true)               // Allow solid 7z archives (default: false)
  .withZipConsistency('ignore')               // ZIP structure policy: 'enforce' (default) or 'ignore'
  .withRepeatedPaths('refuse')                // Reject an archive that names one path twice; 'keep_first' (default) keeps the first copy
  .withParallelDecodeMemory(256 * 1024 * 1024) // 7z LZMA2 lookahead memory (default 128 MiB); null decodes on one thread
  .withMaxSolidCompressionRatio(n)            // Ratio limit of a solid 7z block; only while solid archives are allowed
  .withMaxTarMetadataBytes(bytes)             // TAR metadata budget (default 4 MiB)
  .withMaxDecoderMemory(bytes)                // Decoder dictionary/window memory (default 256 MiB)
  .withCompressedMemberAllowance(n)           // Base gzip members / bzip2 streams of a compressed TAR (default 10,000)
  .withAllowWindowsReservedNames(true);       // Allow CON, NUL, COM1, ... components (on disk checked on Windows only, in-memory on every host; default: false)

An error whose relaxableBy or setting names one of these says which call relaxes it.

List options. listArchive* take an optional ListOptions (third argument for the path functions, options before format for the in-memory ones): new ListOptions().withStoredTargets('read') reads the symlink targets a 7z archive keeps in compressed entry data, which decodes part of the archive; the default 'skip' reports them as 'unread'.

Getters: maxTarMetadataBytes, maxDecoderMemory, compressedMemberAllowance, maxSolidCompressionRatio (null while solid archives are not allowed) and allowWindowsReservedNames return the settings above. allowedExtensions returns the allowlist, or null while every extension is allowed. allowSymlinks, allowHardlinks, allowAbsolutePaths, allowWorldWritable, allowSolidArchives — each returns the corresponding boolean policy value. zipConsistency returns 'enforce' or 'ignore'. parallelDecodeMemory returns the 7z lookahead memory in bytes, or null when decoding runs on one thread. Each extract or verify call may start up to 16 worker threads and hold its own lookahead, so concurrent calls multiply both.

Selecting and rewriting entries

includePatterns, excludePatterns, stripComponents and flatten live on SecurityConfig, so extractArchive*, extractArchiveToMemory, extractArchiveToCallback, listArchive* and verifyArchive* apply the same selection with the same code. Order of operations: the original entry name is validated first (an unsafe name is refused even when it is not selected), then include and exclude patterns select entries, matching the path before stripping, then stripComponents or flatten rewrite the name, which is validated again. Patterns are globs (*, ?, [a-c], **; see exclude patterns above), match raw bytes and are case-sensitive on every host. An empty pattern list selects everything.

  • Entries left out are counted in skipped as 'not_selected', and entries with no component left after stripping, or directories under flatten, as 'stripped_away'. They are not charged to the size limits.
  • An include pattern that matches nothing fails the extraction after the scan with INVALID_CONFIGURATION (setting 'entry_include') and unmatchedPatterns; 'atomic' rolls back. An exclude pattern that matches nothing is not an error.
  • A hardlink whose target the selection leaves out, and any symlink or hardlink under flatten, are refused with SECURITY_VIOLATION (subCode 'LINK_TARGET' and 'LINK_POLICY').
  • 'atomic_replace' staging with a non-default selection is refused (INVALID_CONFIGURATION, setting 'entry_selection').
  • listArchive* still lists every entry and adds dispositions: one object per entry, { action: 'extract', path, landing }, { action: 'skip', path, kind } (kind is the SkipKind) or { action: 'refuse', path } (validation refuses the entry), computed with the listing's SecurityConfig. verifyArchive* reports the refusals extraction would raise for the same selection as issues.

Security Features

The library provides built-in protection against:

| Protection | Description | |------------|-------------| | Path traversal | Blocks ../ and absolute paths | | Symlink attacks | Prevents symlinks escaping extraction directory | | Hardlink attacks | Validates hardlink targets | | Zip bombs | Detects high compression ratios | | TAR metadata bombs | Bounds GNU long-name/long-link and PAX header record reads | | Permission sanitization | Strips setuid/setgid bits | | Size limits | Enforces file and total size limits |

Caution: Unlike many Node.js archive libraries, exarch applies security validation by default.

Supported Formats

| Format | Extensions | Extract | Create | List | Verify | |--------|------------|:-------:|:------:|:----:|:------:| | TAR | .tar | ✅ | ✅ | ✅ | ✅ | | TAR+GZIP | .tar.gz, .tgz | ✅ | ✅ | ✅ | ✅ | | TAR+BZIP2 | .tar.bz2, .tbz2 | ✅ | ✅ | ✅ | ✅ | | TAR+XZ | .tar.xz, .txz | ✅ | ✅ | ✅ | ✅ | | TAR+ZSTD | .tar.zst, .tzst | ✅ | ✅ | ✅ | ✅ | | ZIP | .zip | ✅ | ✅ | ✅ | ✅ | | ZIP-family | .jar, .war, .ear, .nar, .nbm, .apk, .aab, .ipa, .appx, .msix, .whl, .vsix, .xpi, .epub | ✅ | — | ✅ | ✅ | | 7z | .7z | ✅ | — | ✅ | ✅ |

Note: ZIP-family formats share the ZIP container but add extra structure (signing, checksum manifests, ordering rules) that exarch doesn't produce, so creation is rejected for those extensions. 7z creation is not yet supported. Solid and encrypted 7z archives are rejected for security reasons. A 7z archive holding a Windows reparse point is refused as a whole; a Unix S_IFLNK symlink is read and validated through the symlink policy, so it is created only with symlinks allowed, and a 7z FIFO, socket or device node is refused.

Comparison with tar-fs

// UNSAFE - tar-fs has known vulnerabilities
const tar = require('tar-fs');
const fs = require('fs');
fs.createReadStream('archive.tar')
  .pipe(tar.extract('/output'));  // May extract outside target directory!

// SAFE - exarch-rs validates all paths
const { extractArchive } = require('exarch-rs');
await extractArchive('archive.tar', '/output');  // Protected by default

Development

This package is built using napi-rs.

# Clone repository
git clone https://github.com/bug-ops/exarch
cd exarch/crates/exarch-node

# Install dependencies
npm install

# Build native module
npm run build

# Run tests
npm test

Related Packages

License

Licensed under either of:

at your option.