bytefold

bytefold reads, audits, normalizes, and writes archives through Web Streams. It runs on Node, Deno, Bun, and browsers without runtime dependencies.

Supported containers include ZIP and TAR, with gzip, bzip2, XZ, Zstandard, and Brotli compression where the runtime provides the required codec. See the format and runtime table for exact coverage.

Install

npm install @ismail-elkorchi/bytefold
bun add @ismail-elkorchi/bytefold
deno add jsr:@ismail-elkorchi/bytefold

Read an untrusted archive

import { openArchive } from "@ismail-elkorchi/bytefold";

const reader = await openArchive("./archive.zip", {
  safetyProfile: "untrusted",
});

try {
  const report = await reader.audit();
  if (!report.isSafe) {
    console.error(report.issues);
    throw new Error("Archive rejected");
  }

  for await (const entry of reader.entries()) {
    if (entry.isDirectory || entry.isSymlink) continue;
    const bytes = await new Response(await entry.open()).arrayBuffer();
    console.log(entry.name, bytes.byteLength);
  }
} finally {
  await reader.close();
}

Audit before opening entry streams when the input is not trusted. Add explicit resource limits for internet-facing workflows; safety profiles provide defaults, not knowledge of your application's budget.

Abort a failed write

import { createArchiveWriter } from "@ismail-elkorchi/bytefold";

const chunks: Uint8Array[] = [];
const output = new WritableStream<Uint8Array>({
  write(chunk) {
    chunks.push(chunk.slice());
  },
});
const source = new TextEncoder().encode("release contents");

const writer = createArchiveWriter("zip", output);
try {
  await writer.add("release.txt", source);
  await writer.close();
} catch (error) {
  await writer.abort(error);
  throw error;
}

close() finalizes a valid archive. abort() releases the output without writing archive trailers. Do not replace abort() with close() on a failed write.

Entry points

Import	Use it for
@ismail-elkorchi/bytefold	Archives and compression, with automatic runtime selection
@ismail-elkorchi/bytefold/zip	Advanced ZIP readers, writers, errors, and codecs
@ismail-elkorchi/bytefold/node/zip	Advanced Node ZIP filesystem extraction
@ismail-elkorchi/bytefold/tar	Advanced TAR readers and writers
@ismail-elkorchi/bytefold/compress	Raw compression streams and runtime capabilities

The package root accepts bytes, ArrayBuffer, Blob/File, Web readable streams, URLs, and local paths. Local paths are available in Node, Deno, and Bun; browsers accept HTTPS URLs and browser-native inputs. The package is ESM-only and requires Node 24 or newer when used on Node.

Security

Archive paths, symlinks, compressed sizes, and headers are attacker-controlled input. Use the untrusted profile, set limits, inspect audit issues, and keep the reader lifecycle inside try/finally.

Password-protected ZIP support is for interoperability. Traditional ZipCrypto is weak and should not be treated as confidential storage.

See SECURITY.md for the threat model and private vulnerability reporting.

Documentation

• Task guides and API reference
• Breaking-change history and migration guide
• Public behavior and format coverage
• Internal architecture