fix: prevent symlink path traversal via pre-existing symlinks during tar extraction

The existing CVE-2026-24884 fix only validates paths using string-based
path.resolve(), which doesn't detect pre-existing symlinks on disk.
An attacker can pre-plant symlinks (e.g. via git clone) that cause
archive extraction to write files to arbitrary locations outside the
extraction directory.

Add isRealPathSafe() which walks each path segment using fs.promises.lstat
and rejects entries where any segment is a symlink resolving outside the
extraction root. Fail closed on unexpected filesystem errors.

Closes GHSA-4c3q-x735-j3r5

Author: fengmk2

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;
@@ -114,6 +165,9 @@ exports.makeUncompressFn = StreamClass => {
 
         // 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;
@@ -123,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;
@@ -131,57 +239,7 @@ exports.makeUncompressFn = StreamClass => {
           .on('error', reject)
           .on('entry', (header, stream, next) => {
             stream.on('end', next);
-            const destFilePath = path.join(resolvedDestDir, stripFileName(strip, header.name, header.type));
-            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);
           });
       });
     });

test/tar/security-GHSA-4c3q-x735-j3r5.test.js

@@ -0,0 +1,209 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const zlib = require('zlib');
+const uuid = require('uuid');
+const assert = require('assert');
+const compressing = require('../..');
+const { createTarBuffer } = require('../util');
+
+describe('test/tar/security-GHSA-4c3q-x735-j3r5.test.js', () => {
+  let tempDir;
+
+  beforeEach(() => {
+    tempDir = path.join(os.tmpdir(), uuid.v4());
+    fs.mkdirSync(tempDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  function gzipBuffer(buf) {
+    return new Promise((resolve, reject) => {
+      zlib.gzip(buf, (err, result) => {
+        if (err) return reject(err);
+        resolve(result);
+      });
+    });
+  }
+
+  describe('pre-existing symlink file pointing outside destDir', () => {
+    it('should block file write through pre-existing symlink to external file', async () => {
+      const destDir = path.join(tempDir, 'dest');
+      const outsideDir = path.join(tempDir, 'outside');
+      const sensitiveFile = path.join(outsideDir, 'target.txt');
+
+      // Setup: create the sensitive file and a pre-existing symlink in destDir
+      fs.mkdirSync(outsideDir, { recursive: true });
+      fs.writeFileSync(sensitiveFile, 'ORIGINAL_SAFE_CONTENT');
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.symlinkSync(sensitiveFile, path.join(destDir, 'config_file'));
+
+      // Create a tar with a regular file entry matching the symlink name
+      const tarBuffer = await createTarBuffer([
+        { name: 'config_file', type: 'file', content: 'MALICIOUS_OVERWRITE' },
+      ]);
+
+      await compressing.tar.uncompress(tarBuffer, destDir);
+
+      // The sensitive file should NOT have been overwritten
+      assert.strictEqual(
+        fs.readFileSync(sensitiveFile, 'utf8'),
+        'ORIGINAL_SAFE_CONTENT',
+        'Sensitive file should not be overwritten through pre-existing symlink'
+      );
+    });
+  });
+
+  describe('pre-existing symlink directory pointing outside destDir', () => {
+    it('should block file write through pre-existing symlink directory', async () => {
+      const destDir = path.join(tempDir, 'dest');
+      const outsideDir = path.join(tempDir, 'outside');
+
+      // Setup: create outside dir and a symlink directory in destDir
+      fs.mkdirSync(outsideDir, { recursive: true });
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.symlinkSync(outsideDir, path.join(destDir, 'subdir'));
+
+      // Create a tar with a file inside the symlink directory
+      const tarBuffer = await createTarBuffer([
+        { name: 'subdir/secret.txt', type: 'file', content: 'MALICIOUS_DATA' },
+      ]);
+
+      await compressing.tar.uncompress(tarBuffer, destDir);
+
+      // The file should NOT exist in the outside directory
+      assert.strictEqual(
+        fs.existsSync(path.join(outsideDir, 'secret.txt')),
+        false,
+        'File should not be written through pre-existing symlink directory'
+      );
+    });
+  });
+
+  describe('deeply nested pre-existing symlink', () => {
+    it('should block file write through nested symlink escape', async () => {
+      const destDir = path.join(tempDir, 'dest');
+      const outsideDir = path.join(tempDir, 'outside');
+
+      // Setup: create real directories and a symlink deep in the tree
+      fs.mkdirSync(path.join(destDir, 'a', 'b'), { recursive: true });
+      fs.mkdirSync(outsideDir, { recursive: true });
+      fs.symlinkSync(outsideDir, path.join(destDir, 'a', 'b', 'c'));
+
+      // Create a tar with a file through the deep symlink
+      const tarBuffer = await createTarBuffer([
+        { name: 'a/b/c/file.txt', type: 'file', content: 'ESCAPED_DATA' },
+      ]);
+
+      await compressing.tar.uncompress(tarBuffer, destDir);
+
+      // The file should NOT exist in the outside directory
+      assert.strictEqual(
+        fs.existsSync(path.join(outsideDir, 'file.txt')),
+        false,
+        'File should not be written through deeply nested symlink'
+      );
+    });
+  });
+
+  describe('pre-existing symlink pointing within destDir (should be allowed)', () => {
+    it('should allow file write through symlink that stays within destDir', async () => {
+      const destDir = path.join(tempDir, 'dest');
+      const realDir = path.join(destDir, 'real');
+
+      // Setup: create real directory and internal symlink
+      fs.mkdirSync(realDir, { recursive: true });
+      fs.symlinkSync(realDir, path.join(destDir, 'link'));
+
+      // Create a tar with a file through the internal symlink
+      const tarBuffer = await createTarBuffer([
+        { name: 'link/newfile.txt', type: 'file', content: 'safe content' },
+      ]);
+
+      await compressing.tar.uncompress(tarBuffer, destDir);
+
+      // The file SHOULD exist since the symlink points within destDir
+      assert.strictEqual(
+        fs.readFileSync(path.join(realDir, 'newfile.txt'), 'utf8'),
+        'safe content',
+        'File should be written through internal symlink'
+      );
+    });
+  });
+
+  describe('directory entry through pre-existing external symlink', () => {
+    it('should block directory creation through pre-existing symlink', async () => {
+      const destDir = path.join(tempDir, 'dest');
+      const outsideDir = path.join(tempDir, 'outside');
+
+      // Setup
+      fs.mkdirSync(outsideDir, { recursive: true });
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.symlinkSync(outsideDir, path.join(destDir, 'escape'));
+
+      // Create a tar with a directory entry through the symlink
+      const tarBuffer = await createTarBuffer([
+        { name: 'escape/newdir/', type: 'directory' },
+      ]);
+
+      await compressing.tar.uncompress(tarBuffer, destDir);
+
+      // The directory should NOT exist in the outside directory
+      assert.strictEqual(
+        fs.existsSync(path.join(outsideDir, 'newdir')),
+        false,
+        'Directory should not be created through pre-existing symlink'
+      );
+    });
+  });
+
+  describe('tgz format shares the same protection', () => {
+    it('should block file write through pre-existing symlink in tgz extraction', async () => {
+      const destDir = path.join(tempDir, 'dest');
+      const outsideDir = path.join(tempDir, 'outside');
+      const sensitiveFile = path.join(outsideDir, 'target.txt');
+
+      // Setup
+      fs.mkdirSync(outsideDir, { recursive: true });
+      fs.writeFileSync(sensitiveFile, 'ORIGINAL_SAFE_CONTENT');
+      fs.mkdirSync(destDir, { recursive: true });
+      fs.symlinkSync(sensitiveFile, path.join(destDir, 'config_file'));
+
+      // Create a tgz buffer
+      const tarBuffer = await createTarBuffer([
+        { name: 'config_file', type: 'file', content: 'MALICIOUS_OVERWRITE' },
+      ]);
+      const tgzBuffer = await gzipBuffer(tarBuffer);
+
+      await compressing.tgz.uncompress(tgzBuffer, destDir);
+
+      // The sensitive file should NOT have been overwritten
+      assert.strictEqual(
+        fs.readFileSync(sensitiveFile, 'utf8'),
+        'ORIGINAL_SAFE_CONTENT',
+        'TGZ: Sensitive file should not be overwritten through pre-existing symlink'
+      );
+    });
+  });
+
+  describe('normal extraction still works (regression)', () => {
+    it('should extract files normally when no pre-existing symlinks', async () => {
+      const destDir = path.join(tempDir, 'dest');
+
+      const tarBuffer = await createTarBuffer([
+        { name: 'file1.txt', type: 'file', content: 'content1' },
+        { name: 'subdir/', type: 'directory' },
+        { name: 'subdir/file2.txt', type: 'file', content: 'content2' },
+      ]);
+
+      await compressing.tar.uncompress(tarBuffer, destDir);
+
+      assert.strictEqual(fs.readFileSync(path.join(destDir, 'file1.txt'), 'utf8'), 'content1');
+      assert.strictEqual(fs.readFileSync(path.join(destDir, 'subdir/file2.txt'), 'utf8'), 'content2');
+    });
+  });
+});