📦 untarl

Tar and tar.gz extraction with no dependencies and no Node APIs

Reads a .tar or .tar.gz on workerd, in the browser, in Bun and in Node, with the same code and zero dependencies. Gzip is handled by the platform's own DecompressionStream('gzip') rather than a bundled inflater, which is what keeps the dependency count at zero and the bundle cost at nothing.

📋 Table of Contents

• Why
• Install
• Usage
• API
• Untrusted Input
• Out of Scope
• Testing
• Related Repositories
• License

🎯 Why

The original problem was installing a Drupal contrib module at runtime, which means reading a drupal.org .tar.gz from inside a Cloudflare Worker. Two obvious answers were both closed:

1. Do it in PHP. The wasm build has neither ext-zip nor ext-phar, and adding either is a multi-hour Docker rebuild of the interpreter.
2. Use a tar library. Every popular one reaches for node:zlib, node:fs or Buffer. workerd has none of those.

What workerd does have is DecompressionStream('gzip'), natively. And tar is nothing but 512-byte blocks with an octal header. So the whole job fits in ~320 lines of platform-only JavaScript, out where await is legal and no build flag has to change.

📥 Install

bun add @drupflare/untarl

One entry point. The exports map declares . and ./package.json and nothing else, so every symbol arrives from @drupflare/untarl and @drupflare/untarl/src/untar.ts is refused by the resolver. A second name for the only module would be two ways to import the same thing with no way to say which is canonical; the sibling cartridge splits by subpath because its modules have different dependency costs, and here there are none to differ.

🚀 Usage

The common case is two calls: inflate and parse, then flatten to the files you want to write.

import { tarEntryTree, untarGzip } from '@drupflare/untarl';

const response = await fetch('https://ftp.drupal.org/files/projects/token-8.x-1.15.tar.gz');
const entries = await untarGzip(response.body!);

// strip = 1 drops the `token/` wrapper every drupal.org tarball has
for (const [path, bytes] of tarEntryTree(entries, 1)) {
  // write `bytes` to `path` here
}

If you already hold the bytes, or the archive is not gzipped, skip straight to the parser:

import { parseTar } from '@drupflare/untarl';

const entries = parseTar(new Uint8Array(await file.arrayBuffer()));
const names = entries.filter((e) => e.type === 'file').map((e) => e.name);

🔧 API

The split between the two error types is the design. parseTar() is faithful to the bytes and will happily hand back an entry whose name climbs out of the target directory with .. segments. tarEntryTree() decides what is safe to write and is the only layer that throws TarPathError. Separating them lets you inspect a hostile archive without a parser that lies about its contents.

🛡 Untrusted Input

A tarball off the network is untrusted, so every read is bounds-checked and every failure is a named error rather than a read past the end of the buffer, an infinite loop, or a plausible empty result.

The header checksum at offset 148 is not enforced. Writers disagree on whether that field sums the bytes as signed or unsigned, so enforcing it rejects real archives; the octal and bounds checks already stop a malformed header from being read. That is a decision, not an omission.

🚫 Out of Scope

• It does not stream the parse. The archive is buffered whole, because a tar header carries no back-pointer: an entry cannot be found without walking every block before it. For a contrib module that is a few megabytes, which is the size this was built for.
• It does not follow links. Symlinks, hard links and device nodes are consumed and dropped. Nothing in a module install should follow one.
• It does not write files. tarEntryTree() hands you a Map; where those bytes land is yours.
• It does not create archives. Extraction only.

It does handle the shapes real drupal.org tarballs contain: the ustar prefix split, GNU L long names, pax x/g headers (skipped, though an x header's path= record renames the entry it describes), and the v7 habit of writing a directory as typeflag 0 with a trailing slash.

🧪 Testing

bun run typecheck
bun run test # 89 assertions across 2 specs
bun run test:coverage

89 passing, at 98.68% statements, over archives built in the spec rather than checked-in fixtures, so every refusal above has a case that trips it.

Two lines are uncovered. src/untar.ts:75 is the byteAt() bounds guard. Every header read sits inside a block the loop has already checked, so it cannot fire from parseTar(). src/untar.ts:214 is the "does not advance" guard, which is provably unreachable: next is headerAt + 512 + ceil(size / 512) * 512, so next <= headerAt cannot hold while a header is a whole block. It stays because the failure it guards against is a hang rather than an error.

🔗 Related Repositories

📄 License

MIT (c) Gregory Mitchell 2026. See LICENSE.