compressing 2.0.1 → 2.1.1

package/README.md

@@ -8,11 +8,11 @@
 ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/node-modules/compressing)
 
 [npm-image]: https://img.shields.io/npm/v/compressing.svg?style=flat-square
-[npm-url]: https://npmjs.org/package/compressing
+[npm-url]: https://npmx.dev/package/compressing
 [codecov-image]: https://codecov.io/gh/node-modules/compressing/branch/master/graph/badge.svg
 [codecov-url]: https://codecov.io/gh/node-modules/compressing
 [download-image]: https://img.shields.io/npm/dm/compressing.svg?style=flat-square
-[download-url]: https://npmjs.org/package/compressing
+[download-url]: https://npmx.dev/package/compressing
 
 The missing compressing and uncompressing lib for node.
 
@@ -280,6 +280,7 @@ Params
     - Korean: cp949, euc-kr
     - Japanese: sjis (shift_jis), cp932, euc-jp
     - Chinese: gbk, gb18030, gb2312, cp936, hkscs, big5, cp950
+  - opts.strip {Number} - Strip leading path segments when extracting (tar/tgz/zip). Default is 0.
 
 ### FileStream
 
@@ -359,6 +360,7 @@ __Constructor__
 Common params:
 
 - opts.source {String|Buffer|Stream} - source to be uncompressed, could be a file path, buffer, or a readable stream.
+- opts.strip {Number} - Strip leading path segments when extracting (tar/tgz/zip). Default is 0.
 
 __CAUTION for zip.UncompressStream__
 

package/lib/utils.js

@@ -20,6 +20,57 @@ function isPathWithinParent(childPath, parentPath) {
          normalizedChild.startsWith(parentWithSep);
 }
 
+/**
+ * Check if the real filesystem path stays within parentDir,
+ * accounting for pre-existing symlinks on disk.
+ * Walks each path segment from parentDir to targetPath using lstat.
+ * If any segment is a symlink, resolves it and verifies it stays within parentDir.
+ * @param {string} targetPath - Absolute path to validate
+ * @param {string} parentDir - Absolute path of the extraction root
+ * @param {string} realParentDir - Pre-resolved real path of parentDir (handles OS-level symlinks like /var -> /private/var on macOS)
+ * @returns {Promise<boolean>} true if safe, false if any segment escapes via symlink
+ */
+async function isRealPathSafe(targetPath, parentDir, realParentDir) {
+  function isWithinParent(p) {
+    return isPathWithinParent(p, parentDir) || isPathWithinParent(p, realParentDir);
+  }
+
+  const relative = path.relative(parentDir, targetPath);
+  const segments = relative.split(path.sep);
+  let current = parentDir;
+  for (const segment of segments) {
+    if (!segment || segment === '.') continue;
+    current = path.join(current, segment);
+    try {
+      const stat = await fs.promises.lstat(current);
+      if (stat.isSymbolicLink()) {
+        let resolved;
+        try {
+          resolved = await fs.promises.realpath(current);
+        } catch (e) {
+          if (e.code === 'ENOENT') {
+            // Dangling symlink - check textual target
+            const linkTarget = await fs.promises.readlink(current);
+            const absTarget = path.resolve(path.dirname(current), linkTarget);
+            return isWithinParent(absTarget);
+          }
+          // Fail closed: unexpected errors during symlink resolution are unsafe
+          return false;
+        }
+        if (!isWithinParent(resolved)) {
+          return false;
+        }
+        current = resolved;
+      }
+    } catch (e) {
+      if (e.code === 'ENOENT') break; // Path doesn't exist yet, safe
+      // Fail closed: unexpected filesystem errors are unsafe
+      return false;
+    }
+  }
+  return true;
+}
+
 // file/fileBuffer/stream
 exports.sourceType = source => {
   if (!source) return undefined;
@@ -104,12 +155,19 @@ exports.makeUncompressFn = StreamClass => {
       throw error;
     }
 
+    const strip = opts.strip ? Number(opts.strip) : 0;
+    // Strip is handled here in makeUncompressFn, so remove it from opts to avoid passing to UncompressStream
+    delete opts.strip;
+
     return new Promise((resolve, reject) => {
       fs.mkdir(destDir, { recursive: true }, err => {
         if (err) return reject(err);
 
         // Resolve destDir to absolute path for security validation
         const resolvedDestDir = path.resolve(destDir);
+        // Resolve once for the entire extraction to handle OS-level symlinks
+        // (e.g. /var -> /private/var on macOS)
+        const realDestDirPromise = fs.promises.realpath(resolvedDestDir).catch(() => resolvedDestDir);
 
         let entryCount = 0;
         let successCount = 0;
@@ -119,6 +177,60 @@ exports.makeUncompressFn = StreamClass => {
           if (isFinish && entryCount === successCount) resolve();
         }
 
+        async function processEntry(header, stream) {
+          const destFilePath = path.join(resolvedDestDir, stripFileName(strip, header.name, header.type));
+          const resolvedDestPath = path.resolve(destFilePath);
+
+          if (!isPathWithinParent(resolvedDestPath, resolvedDestDir)) {
+            console.warn(`[compressing] Skipping entry with path traversal: "${header.name}" -> "${resolvedDestPath}"`);
+            stream.resume();
+            return;
+          }
+
+          const realDestDir = await realDestDirPromise;
+          if (!await isRealPathSafe(resolvedDestPath, resolvedDestDir, realDestDir)) {
+            console.warn(`[compressing] Skipping entry "${header.name}": a symlink in its path resolves outside the extraction directory`);
+            stream.resume();
+            return;
+          }
+
+          if (header.type === 'file') {
+            const dir = path.dirname(destFilePath);
+            await fs.promises.mkdir(dir, { recursive: true });
+            entryCount++;
+            pump(stream, fs.createWriteStream(destFilePath, { mode: opts.mode || header.mode }), err => {
+              if (err) return reject(err);
+              successCount++;
+              done();
+            });
+          } else if (header.type === 'symlink') {
+            const dir = path.dirname(destFilePath);
+            const target = path.resolve(dir, header.linkname);
+
+            if (!isPathWithinParent(target, resolvedDestDir)) {
+              console.warn(`[compressing] Skipping symlink "${header.name}": target "${target}" escapes extraction directory`);
+              stream.resume();
+              return;
+            }
+
+            if (!await isRealPathSafe(target, resolvedDestDir, realDestDir)) {
+              console.warn(`[compressing] Skipping symlink "${header.name}": target resolves outside extraction directory via existing symlink`);
+              stream.resume();
+              return;
+            }
+
+            entryCount++;
+            await fs.promises.mkdir(dir, { recursive: true });
+            const relativeTarget = path.relative(dir, target);
+            await fs.promises.symlink(relativeTarget, destFilePath);
+            successCount++;
+            stream.resume();
+          } else { // directory
+            await fs.promises.mkdir(destFilePath, { recursive: true });
+            stream.resume();
+          }
+        }
+
         new StreamClass(opts)
           .on('finish', () => {
             isFinish = true;
@@ -127,57 +239,7 @@ exports.makeUncompressFn = StreamClass => {
           .on('error', reject)
           .on('entry', (header, stream, next) => {
             stream.on('end', next);
-            const destFilePath = path.join(resolvedDestDir, header.name);
-            const resolvedDestPath = path.resolve(destFilePath);
-
-            // Security: Validate that the entry path doesn't escape the destination directory
-            if (!isPathWithinParent(resolvedDestPath, resolvedDestDir)) {
-              console.warn(`[compressing] Skipping entry with path traversal: "${header.name}" -> "${resolvedDestPath}"`);
-              stream.resume();
-              return;
-            }
-
-            if (header.type === 'file') {
-              const dir = path.dirname(destFilePath);
-              fs.mkdir(dir, { recursive: true }, err => {
-                if (err) return reject(err);
-
-                entryCount++;
-                pump(stream, fs.createWriteStream(destFilePath, { mode: opts.mode || header.mode }), err => {
-                  if (err) return reject(err);
-                  successCount++;
-                  done();
-                });
-              });
-            } else if (header.type === 'symlink') {
-              const dir = path.dirname(destFilePath);
-              const target = path.resolve(dir, header.linkname);
-
-              // Security: Validate that the symlink target doesn't escape the destination directory
-              if (!isPathWithinParent(target, resolvedDestDir)) {
-                console.warn(`[compressing] Skipping symlink "${header.name}": target "${target}" escapes extraction directory`);
-                stream.resume();
-                return;
-              }
-
-              entryCount++;
-
-              fs.mkdir(dir, { recursive: true }, err => {
-                if (err) return reject(err);
-
-                const relativeTarget = path.relative(dir, target);
-                fs.symlink(relativeTarget, destFilePath, err => {
-                  if (err) return reject(err);
-                  successCount++;
-                  stream.resume();
-                });
-              });
-            } else { // directory
-              fs.mkdir(destFilePath, { recursive: true }, err => {
-                if (err) return reject(err);
-                stream.resume();
-              });
-            }
+            processEntry(header, stream).catch(reject);
           });
       });
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "compressing",
-  "version": "2.0.1",
+  "version": "2.1.1",
   "description": "Everything you need for compressing and uncompressing",
   "main": "index.js",
   "scripts": {