modern-tar 0.2.0 → 0.2.2

package/README.md

@@ -59,7 +59,8 @@ const entries = [
 const tarBuffer = await packTar(entries);
 
 // Unpack tar buffer into entries
-for await (const entry of unpackTar(tarBuffer)) {
+const entries = await unpackTar(tarBuffer);
+for (const entry of entries) {
 	console.log(`File: ${entry.header.name}`);
 	const content = new TextDecoder().decode(entry.data);
 	console.log(`Content: ${content}`);
@@ -114,7 +115,8 @@ if (!response.body) throw new Error('No response body');
 const tarStream = response.body.pipeThrough(createGzipDecoder());
 
 // Use `unpackTar` for buffered extraction or `createTarDecoder` for streaming
-for await (const entry of unpackTar(tarStream)) {
+const entries = await unpackTar(tarStream);
+for (const entry of entries) {
 	console.log(`Extracted: ${entry.header.name}`);
 	const content = new TextDecoder().decode(entry.data);
 	console.log(`Content: ${content}`);
@@ -167,7 +169,8 @@ const extractStream = unpackTar('./output', {
 
 	// Filesystem-specific options
 	fmode: 0o644, // Override file permissions
-	dmode: 0o755  // Override directory permissions
+	dmode: 0o755, // Override directory permissions
+	maxDepth: 50  // Limit extraction depth for security (default: 1024)
 });
 
 await pipeline(sourceStream, extractStream);
@@ -418,7 +421,7 @@ interface ParsedTarEntry {
 // Output entry from a buffered unpack function
 interface ParsedTarEntryWithData {
 	header: TarHeader;
-	data: Uint8Array;
+	data: Uint8Array<ArrayBuffer>;
 }
 
 // Platform-neutral configuration for unpacking
@@ -492,6 +495,14 @@ interface UnpackOptionsFS extends UnpackOptions {
    * @default true
    */
   validateSymlinks?: boolean;
+  /**
+   * The maximum depth of paths to extract. Prevents Denial of Service (DoS) attacks
+   * from malicious archives with deeply nested directories.
+   *
+   * Set to `Infinity` to disable depth checking (not recommended for untrusted archives).
+   * @default 1024
+   */
+  maxDepth?: number;
 }
 ```
 

package/dist/fs/index.d.ts

@@ -1,4 +1,4 @@
-import { TarEntryData, TarHeader, UnpackOptions } from "../index-Dx4tbuJh.js";
+import { TarEntryData, TarHeader, UnpackOptions } from "../index-G8Ie88oV.js";
 import { Stats } from "node:fs";
 import { Readable, Writable } from "node:stream";
 
@@ -34,6 +34,14 @@ interface UnpackOptionsFS extends UnpackOptions {
    * @default true
    */
   validateSymlinks?: boolean;
+  /**
+   * The maximum depth of paths to extract. Prevents Denial of Service (DoS) attacks
+   * from malicious archives with deeply nested directories.
+   *
+   * Set to `Infinity` to disable depth checking (not recommended for untrusted archives).
+   * @default 1024
+   */
+  maxDepth?: number;
 }
 /** Describes a file on the local filesystem to be added to the archive. */
 interface FileSource {

package/dist/fs/index.js

@@ -1,4 +1,4 @@
-import { BLOCK_SIZE, createTarDecoder, createTarHeader, createTarOptionsTransformer, createTarPacker } from "../web-C1b5fAZt.js";
+import { BLOCK_SIZE, createTarDecoder, createTarHeader, createTarOptionsTransformer, createTarPacker } from "../web-DcwR3pag.js";
 import { createReadStream, createWriteStream } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
@@ -258,35 +258,35 @@ function unpackTar(directoryPath, options = {}) {
 		}
 	});
 	const processingPromise = (async () => {
-		const resolvedDestDir = path.resolve(directoryPath);
-		const createdDirs = /* @__PURE__ */ new Set();
+		const resolvedDestDir = normalizePath(path.resolve(directoryPath));
+		const validatedDirs = new Set([resolvedDestDir]);
 		await fs.mkdir(resolvedDestDir, { recursive: true });
-		createdDirs.add(resolvedDestDir);
 		const reader = readable.pipeThrough(createTarDecoder()).pipeThrough(createTarOptionsTransformer(options)).getReader();
 		try {
+			const maxDepth = options.maxDepth ?? 1024;
 			while (true) {
 				const { done, value: entry } = await reader.read();
 				if (done) break;
 				const { header } = entry;
-				if (path.isAbsolute(header.name)) throw new Error(`Path traversal attempt detected for entry "${header.name}".`);
-				const outPath = path.join(resolvedDestDir, header.name);
-				if (!outPath.startsWith(resolvedDestDir)) throw new Error(`Path traversal attempt detected for entry "${header.name}".`);
-				const parentDir = path.dirname(outPath);
-				if (!createdDirs.has(parentDir)) {
-					await fs.mkdir(parentDir, { recursive: true });
-					createdDirs.add(parentDir);
+				const normalizedName = normalizePath(header.name);
+				if (maxDepth !== Infinity) {
+					const depth = normalizedName.split("/").length;
+					if (depth > maxDepth) throw new Error(`Path depth of entry "${header.name}" (${depth}) exceeds the maximum allowed depth of ${maxDepth}.`);
 				}
+				if (path.isAbsolute(normalizedName)) throw new Error(`Path traversal attempt detected for entry "${header.name}".`);
+				const outPath = path.join(resolvedDestDir, normalizedName);
+				validateBounds(outPath, resolvedDestDir, `Path traversal attempt detected for entry "${header.name}".`);
+				const parentDir = path.dirname(outPath);
+				await validatePath(parentDir, resolvedDestDir, validatedDirs);
+				await fs.mkdir(parentDir, { recursive: true });
 				switch (header.type) {
 					case "directory": {
 						const mode = options.dmode ?? header.mode;
-						if (createdDirs.has(outPath) && mode) await fs.chmod(outPath, mode);
-						else {
-							await fs.mkdir(outPath, {
-								recursive: true,
-								mode
-							});
-							createdDirs.add(outPath);
-						}
+						await fs.mkdir(outPath, {
+							recursive: true,
+							mode
+						});
+						validatedDirs.add(outPath);
 						break;
 					}
 					case "file":
@@ -296,14 +296,22 @@ function unpackTar(directoryPath, options = {}) {
 						if (!header.linkname) break;
 						if (options.validateSymlinks ?? true) {
 							const symlinkDir = path.dirname(outPath);
-							if (!path.resolve(symlinkDir, header.linkname).startsWith(resolvedDestDir)) throw new Error(`Symlink target "${header.linkname}" points outside the extraction directory.`);
+							const resolvedTarget = path.resolve(symlinkDir, header.linkname);
+							validateBounds(resolvedTarget, resolvedDestDir, `Symlink target "${header.linkname}" points outside the extraction directory.`);
 						}
 						await fs.symlink(header.linkname, outPath);
+						if (process.platform === "win32") {
+							validatedDirs.clear();
+							validatedDirs.add(resolvedDestDir);
+						} else validatedDirs.delete(outPath);
 						break;
 					case "link": {
 						if (!header.linkname) break;
-						const resolvedLinkTarget = path.resolve(resolvedDestDir, header.linkname);
-						if (!resolvedLinkTarget.startsWith(resolvedDestDir)) throw new Error(`Hardlink target "${header.linkname}" points outside the extraction directory.`);
+						const normalizedLinkname = normalizePath(header.linkname);
+						if (path.isAbsolute(normalizedLinkname)) throw new Error(`Hardlink target "${header.linkname}" points outside the extraction directory.`);
+						const resolvedLinkTarget = path.resolve(resolvedDestDir, normalizedLinkname);
+						validateBounds(resolvedLinkTarget, resolvedDestDir, `Hardlink target "${header.linkname}" points outside the extraction directory.`);
+						await validatePath(path.dirname(resolvedLinkTarget), resolvedDestDir, validatedDirs);
 						await fs.link(resolvedLinkTarget, outPath);
 						break;
 					}
@@ -321,6 +329,54 @@ function unpackTar(directoryPath, options = {}) {
 	});
 	return writable;
 }
+/**
+* Recursively validates that each item of the given path exists and is a directory or
+* a safe symlink.
+*
+* We need to call this for each path component to ensure that no symlinks escape the
+* target directory.
+*/
+async function validatePath(currentPath, root, cache) {
+	const normalizedPath = normalizePath(currentPath);
+	if (normalizedPath === root || cache.has(normalizedPath)) return;
+	let stat;
+	try {
+		stat = await fs.lstat(normalizedPath);
+	} catch (err) {
+		if (err instanceof Error && "code" in err && (err.code === "ENOENT" || err.code === "EPERM")) {
+			await validatePath(path.dirname(normalizedPath), root, cache);
+			cache.add(normalizedPath);
+			return;
+		}
+		throw err;
+	}
+	if (stat.isDirectory()) {
+		await validatePath(path.dirname(normalizedPath), root, cache);
+		cache.add(normalizedPath);
+		return;
+	}
+	if (stat.isSymbolicLink()) {
+		const realPath = await fs.realpath(normalizedPath);
+		validateBounds(realPath, root, `Path traversal attempt detected: symlink "${currentPath}" points outside the extraction directory.`);
+		await validatePath(path.dirname(normalizedPath), root, cache);
+		cache.add(normalizedPath);
+		return;
+	}
+	throw new Error(`Path traversal attempt detected: "${currentPath}" is not a valid directory component.`);
+}
+function validateBounds(targetPath, destDir, errorMessage) {
+	const normalizedTarget = normalizePath(targetPath);
+	if (!(normalizedTarget === destDir || normalizedTarget.startsWith(destDir + path.sep))) throw new Error(errorMessage);
+}
+/**
+* Normalizes a file path to prevent Unicode-based security vulnerabilities.
+*
+* This prevents cache poisoning attacks where different Unicode representations
+* of the same visual path (e.g., "café" vs "cafe´") could bypass validation.
+*/
+function normalizePath(pathStr) {
+	return pathStr.normalize("NFKD");
+}
 
 //#endregion
 export { packTar, packTarSources, unpackTar };

package/dist/{index-Dx4tbuJh.d.ts → index-G8Ie88oV.d.ts}

@@ -131,7 +131,7 @@ interface ParsedTarEntry {
  */
 interface ParsedTarEntryWithData {
   header: TarHeader;
-  data: Uint8Array;
+  data: Uint8Array<ArrayBuffer>;
 }
 /**
  * Platform-neutral configuration options for extracting tar archives.
@@ -227,7 +227,7 @@ declare function packTar(entries: TarEntry[]): Promise<Uint8Array>;
  * }
  * ```
  */
-declare function unpackTar(archive: ArrayBuffer | Uint8Array, options?: UnpackOptions): Promise<ParsedTarEntryWithData[]>;
+declare function unpackTar(archive: ArrayBuffer | Uint8Array | ReadableStream<Uint8Array>, options?: UnpackOptions): Promise<ParsedTarEntryWithData[]>;
 //#endregion
 //#region src/web/options.d.ts
 /**

package/dist/web/index.d.ts

@@ -1,2 +1,2 @@
-import { ParsedTarEntry, ParsedTarEntryWithData, TarEntry, TarEntryData, TarHeader, TarPackController, UnpackOptions, createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar } from "../index-Dx4tbuJh.js";
+import { ParsedTarEntry, ParsedTarEntryWithData, TarEntry, TarEntryData, TarHeader, TarPackController, UnpackOptions, createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar } from "../index-G8Ie88oV.js";
 export { ParsedTarEntry, ParsedTarEntryWithData, TarEntry, TarEntryData, TarHeader, TarPackController, UnpackOptions, createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar };

package/dist/web/index.js

@@ -1,3 +1,3 @@
-import { createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar } from "../web-C1b5fAZt.js";
+import { createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar } from "../web-DcwR3pag.js";
 
 export { createGzipDecoder, createGzipEncoder, createTarDecoder, createTarOptionsTransformer, createTarPacker, packTar, unpackTar };

package/dist/{web-C1b5fAZt.js → web-DcwR3pag.js}

@@ -96,27 +96,23 @@ function createGzipDecoder() {
 function createTarOptionsTransformer(options = {}) {
 	return new TransformStream({ async transform(entry, controller) {
 		let header = entry.header;
-		if (options.strip !== void 0) {
-			if (options.strip < 0) {
+		const stripCount = options.strip;
+		if (stripCount && stripCount > 0) {
+			const newName = stripPathComponents(header.name, stripCount);
+			if (newName === null) {
 				drainStream(entry.body);
-				throw new Error(`Invalid strip value: ${options.strip}. Must be non-negative.`);
+				return;
 			}
-			if (options.strip > 0) {
-				const strippedComponents = header.name.split("/").filter((component) => component.length > 0).slice(options.strip);
-				if (strippedComponents.length === 0) {
-					drainStream(entry.body);
-					return;
-				}
-				const strippedName = strippedComponents.join("/");
-				if (header.type === "directory" && !strippedName.endsWith("/")) header = {
-					...header,
-					name: `${strippedName}/`
-				};
-				else header = {
-					...header,
-					name: strippedName
-				};
+			let newLinkname = header.linkname;
+			if (newLinkname?.startsWith("/")) {
+				const strippedLinkTarget = stripPathComponents(newLinkname, stripCount);
+				newLinkname = strippedLinkTarget === null ? "/" : `/${strippedLinkTarget}`;
 			}
+			header = {
+				...header,
+				name: header.type === "directory" && !newName.endsWith("/") ? `${newName}/` : newName,
+				linkname: newLinkname
+			};
 		}
 		if (options.filter && options.filter(header) === false) {
 			drainStream(entry.body);
@@ -130,6 +126,14 @@ function createTarOptionsTransformer(options = {}) {
 	} });
 }
 /**
+* Strips the specified number of leading path components from a given path.
+*/
+function stripPathComponents(path, stripCount) {
+	const components = path.split("/").filter((c) => c.length > 0);
+	if (stripCount >= components.length) return null;
+	return components.slice(stripCount).join("/");
+}
+/**
 * Drains the stream asynchronously without blocking the transform stream.
 */
 function drainStream(stream) {
@@ -694,15 +698,25 @@ async function packTar(entries) {
 * ```
 */
 async function unpackTar(archive, options = {}) {
-	const sourceStream = ReadableStream.from([archive instanceof Uint8Array ? archive : new Uint8Array(archive)]);
+	const sourceStream = archive instanceof ReadableStream ? archive : new ReadableStream({ start(controller) {
+		const data = archive instanceof Uint8Array ? archive : new Uint8Array(archive);
+		controller.enqueue(data);
+		controller.close();
+	} });
 	const results = [];
-	const entryStream = sourceStream.pipeThrough(createTarDecoder()).pipeThrough(createTarOptionsTransformer(options));
-	for await (const entry of entryStream) {
-		const data = new Uint8Array(await new Response(entry.body).arrayBuffer());
-		results.push({
-			header: entry.header,
-			data
-		});
+	const reader = sourceStream.pipeThrough(createTarDecoder()).pipeThrough(createTarOptionsTransformer(options)).getReader();
+	try {
+		while (true) {
+			const { done, value: entry } = await reader.read();
+			if (done) break;
+			const data = new Uint8Array(await new Response(entry.body).arrayBuffer());
+			results.push({
+				header: entry.header,
+				data
+			});
+		}
+	} finally {
+		reader.releaseLock();
 	}
 	return results;
 }

package/package.json

@@ -1,7 +1,8 @@
 {
 	"name": "modern-tar",
-	"version": "0.2.0",
+	"version": "0.2.2",
 	"description": "Zero dependency streaming tar parser and writer for JavaScript.",
+	"author": "Ayuhito <hello@ayuhito.com>",
 	"license": "MIT",
 	"type": "module",
 	"sideEffects": false,
@@ -48,7 +49,6 @@
 		"type": "git",
 		"url": "git+https://github.com/ayuhito/modern-tar.git"
 	},
-	"author": "Ayuhito <hello@ayuhito.com>",
 	"publishConfig": {
 		"access": "public"
 	},