zip-lib 1.2.2 → 1.3.0

package/lib/unzip.js

@@ -4,6 +4,7 @@ exports.Unzip = void 0;
 const node_fs_1 = require("node:fs");
 const fs = require("node:fs/promises");
 const path = require("node:path");
+const promises_1 = require("node:stream/promises");
 const yauzl = require("yauzl");
 const cancelable_1 = require("./cancelable");
 const exfs = require("./fs");
@@ -41,6 +42,7 @@ class EntryContext {
         this.symlinkAsFileOnWindows = symlinkAsFileOnWindows;
         this._symlinkFileNames = [];
         this._symlinkFolders = [];
+        this._inspectedFolders = [];
         this._ensuredFolders = [];
     }
     get decodeEntryFileName() {
@@ -64,25 +66,38 @@ class EntryContext {
             this._symlinkFolders.push({ folder, realpath });
         }
     }
-    isOutside(baseDir, targetPath) {
-        const absoluteBase = path.resolve(baseDir);
-        const absoluteTarget = path.resolve(targetPath);
-        const relative = path.relative(absoluteBase, absoluteTarget);
-        return relative.startsWith("..") || path.isAbsolute(relative);
-    }
     getFilePath() {
         return path.resolve(path.join(this.targetFolder, this.decodeEntryFileName));
     }
+    async inspectFolder(folder) {
+        if (this._inspectedFolders.includes(folder) || folder === path.dirname(folder)) {
+            return;
+        }
+        await this.inspectFolder(path.dirname(folder));
+        const folderStat = await exfs.statFolder(folder);
+        if (!folderStat) {
+            return;
+        }
+        if (folderStat.isSymbolicLink) {
+            this.addSymlinkFolder(folder, folderStat.realpath);
+        }
+        this._inspectedFolders.push(folder);
+    }
     async ensureFolder(folder) {
         if (this._ensuredFolders.includes(folder)) {
             return;
         }
+        await this.inspectFolder(path.dirname(folder));
         const folderStat = await exfs.ensureFolder(folder);
         if (folderStat.isSymbolicLink) {
             this.addSymlinkFolder(folder, folderStat.realpath);
         }
         this._ensuredFolders.push(folder);
     }
+    isSymlinkTargetOutsideTargetFolder(linkTarget, linkFilePath) {
+        const fileDir = path.dirname(linkFilePath);
+        return exfs.isOutside(this.realTargetFolder, path.resolve(fileDir, linkTarget));
+    }
     async isOutsideTargetFolder(tpath) {
         if (this._symlinkFileNames.length === 0 && this._symlinkFolders.length === 0) {
             return false;
@@ -92,7 +107,7 @@ class EntryContext {
         }
         for (const { folder, realpath } of this._symlinkFolders) {
             if (tpath.includes(folder)) {
-                if (this.isOutside(this.realTargetFolder, realpath)) {
+                if (exfs.isOutside(this.realTargetFolder, realpath)) {
                     return true;
                 }
             }
@@ -100,7 +115,7 @@ class EntryContext {
         for (const fileName of this._symlinkFileNames) {
             if (tpath.includes(fileName)) {
                 const realFilePath = await exfs.realpath(tpath);
-                if (this.isOutside(this.realTargetFolder, realFilePath)) {
+                if (exfs.isOutside(this.realTargetFolder, realFilePath)) {
                     return true;
                 }
             }
@@ -119,98 +134,124 @@ class Unzip extends cancelable_1.Cancelable {
         super();
         this.options = options;
     }
-    /**
-     * Extract the zip file to the specified location.
-     * @param zipFile
-     * @param targetFolder
-     * @param options
-     */
-    async extract(zipFile, targetFolder) {
-        let extractedEntriesCount = 0;
+    async extract(zipFileOrBuffer, targetFolder) {
         const token = new cancelable_1.CancellationToken();
         this.token = token;
+        const { zfile, realTargetFolder } = await this.prepareExtraction(zipFileOrBuffer, targetFolder, token);
+        this.zipFile = zfile;
+        await this.processEntries(zfile, targetFolder, realTargetFolder, token);
+    }
+    async prepareExtraction(zipFileOrBuffer, targetFolder, token) {
         if (this.isOverwrite()) {
             await exfs.rimraf(targetFolder);
         }
         if (token.isCancelled) {
-            return Promise.reject(this.canceledError());
+            throw this.canceledError();
         }
         await exfs.ensureFolder(targetFolder);
         const realTargetFolder = await exfs.realpath(targetFolder);
-        const zfile = await this.openZip(zipFile, token);
-        this.zipFile = zfile;
-        zfile.readEntry();
-        return new Promise((c, e) => {
+        const zfile = await this.openZip(zipFileOrBuffer, token);
+        return { zfile, realTargetFolder };
+    }
+    async processEntries(zfile, targetFolder, realTargetFolder, token) {
+        return await new Promise((resolve, reject) => {
+            let extractedEntriesCount = 0;
             let anyError = null;
             const total = zfile.entryCount;
+            const entryContext = new EntryContext(targetFolder, realTargetFolder, this.symlinkToFile());
+            const entryEvent = new EntryEvent(total);
+            const settle = this.createPromiseSettler(resolve, reject);
+            const disposeCancel = token.onCancelled(() => {
+                this.closeZip();
+                settle.reject(this.canceledError());
+            });
             zfile.once("error", (err) => {
+                disposeCancel();
+                anyError = this.wrapError(err, token.isCancelled);
                 this.closeZip();
-                e(this.wrapError(err, token.isCancelled));
+                settle.reject(anyError);
             });
             zfile.once("close", () => {
+                disposeCancel();
                 this.zipFile = null;
                 if (anyError) {
-                    e(this.wrapError(anyError, token.isCancelled));
+                    settle.reject(this.wrapError(anyError, token.isCancelled));
                 }
-                else {
-                    if (token.isCancelled) {
-                        e(this.canceledError());
-                    }
-                    // If the zip content is empty, it will not receive the `zfile.on("entry")` event.
-                    else if (total === 0) {
-                        c(void 0);
-                    }
+                else if (token.isCancelled) {
+                    settle.reject(this.canceledError());
+                }
+                else if (extractedEntriesCount >= total) {
+                    // If the zip content is empty, it will not receive the zfile.on("entry") event.
+                    settle.resolve();
                 }
             });
-            // Because openZip is an asynchronous method, openZip may not be completed when calling cancel,
-            // so we need to check if it has been canceled after the openZip method returns.
-            if (token.isCancelled) {
-                this.closeZip();
-                return;
-            }
-            const entryContext = new EntryContext(targetFolder, realTargetFolder, this.symlinkToFile());
-            const entryEvent = new EntryEvent(total);
             zfile.on("entry", async (entry) => {
-                // use UTF-8 in all situations
-                // see https://github.com/thejoshwolfe/yauzl/issues/84
-                const rawName = entry.fileName.toString("utf8");
-                // allow backslash
-                const fileName = rawName.replace(/\\/g, "/");
-                // Because `decodeStrings` is `false`, we need to manually verify the entryname
-                // see https://github.com/thejoshwolfe/yauzl#validatefilenamefilename
-                const errorMessage = yauzl.validateFileName(fileName);
-                if (errorMessage != null) {
-                    anyError = new Error(errorMessage);
-                    this.closeZip();
-                    e(anyError);
-                    return;
-                }
-                entryEvent.entryName = fileName;
-                this.onEntryCallback(entryEvent);
-                entryContext.decodeEntryFileName = fileName;
                 try {
-                    if (entryEvent.isPrevented) {
-                        entryEvent.reset();
-                        zfile.readEntry();
-                    }
-                    else {
-                        await this.handleEntry(zfile, entry, entryContext, token);
-                    }
+                    await this.handleZipEntry(zfile, entry, entryContext, entryEvent, token);
                     extractedEntriesCount++;
-                    if (extractedEntriesCount === total) {
-                        c();
+                    if (extractedEntriesCount >= total) {
+                        settle.resolve();
                     }
                 }
                 catch (error) {
                     anyError = this.wrapError(error, token.isCancelled);
                     this.closeZip();
-                    e(anyError);
+                    settle.reject(anyError);
                 }
             });
+            this.readNextEntry(zfile, token);
         });
     }
+    readNextEntry(zfile, token) {
+        if (token.isCancelled) {
+            this.closeZip();
+            return;
+        }
+        zfile.readEntry();
+    }
+    createPromiseSettler(resolve, reject) {
+        let settled = false;
+        return {
+            resolve: () => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                resolve();
+            },
+            reject: (error) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                reject(error);
+            },
+        };
+    }
+    async handleZipEntry(zfile, entry, entryContext, entryEvent, token) {
+        // use UTF-8 in all situations
+        // see https://github.com/thejoshwolfe/yauzl/issues/84
+        const rawName = entry.fileName.toString("utf8");
+        // allow backslash
+        const fileName = rawName.replace(/\\/g, "/");
+        // Because decodeStrings is false, we need to manually verify the entry name
+        // see https://github.com/thejoshwolfe/yauzl#validatefilenamefilename
+        const errorMessage = yauzl.validateFileName(fileName);
+        if (errorMessage != null) {
+            throw new Error(errorMessage);
+        }
+        entryEvent.entryName = fileName;
+        this.onEntryCallback(entryEvent);
+        entryContext.decodeEntryFileName = fileName;
+        if (entryEvent.isPrevented) {
+            entryEvent.reset();
+            this.readNextEntry(zfile, token);
+            return;
+        }
+        await this.handleEntry(zfile, entry, entryContext, token);
+    }
     /**
-     * Cancel decompression.
+     * Cancel extraction.
      * If the cancel method is called after the extract is complete, nothing will happen.
      */
     cancel() {
@@ -226,29 +267,41 @@ class Unzip extends cancelable_1.Cancelable {
             this.zipFile = null;
         }
     }
-    openZip(zipFile, token) {
-        return new Promise((c, e) => {
-            yauzl.open(zipFile, {
-                lazyEntries: true,
-                // see https://github.com/thejoshwolfe/yauzl/issues/84
-                decodeStrings: false,
-            }, (err, zfile) => {
-                if (err) {
-                    e(this.wrapError(err, token.isCancelled));
+    async openZip(zipFileOrBuffer, token) {
+        const options = {
+            lazyEntries: true,
+            // see https://github.com/thejoshwolfe/yauzl/issues/84
+            decodeStrings: false,
+        };
+        try {
+            return await new Promise((resolve, reject) => {
+                const callback = (err, zfile) => {
+                    if (err) {
+                        reject(this.wrapError(err, token.isCancelled));
+                    }
+                    else {
+                        resolve(zfile);
+                    }
+                };
+                if (typeof zipFileOrBuffer === "string") {
+                    yauzl.open(zipFileOrBuffer, options, callback);
                 }
                 else {
-                    c(zfile);
+                    yauzl.fromBuffer(zipFileOrBuffer, options, callback);
                 }
             });
-        });
+        }
+        catch (error) {
+            throw this.wrapError(error, token.isCancelled);
+        }
     }
     async handleEntry(zfile, entry, entryContext, token) {
         if (/\/$/.test(entryContext.decodeEntryFileName)) {
             // Directory file names end with '/'.
-            // Note that entires for directories themselves are optional.
+            // Note that entries for directories themselves are optional.
             // An entry's fileName implicitly requires its parent directories to exist.
             await exfs.ensureFolder(entryContext.getFilePath());
-            zfile.readEntry();
+            this.readNextEntry(zfile, token);
         }
         else {
             // file entry
@@ -256,13 +309,13 @@ class Unzip extends cancelable_1.Cancelable {
         }
     }
     openZipFileStream(zfile, entry, token) {
-        return new Promise((c, e) => {
+        return new Promise((resolve, reject) => {
             zfile.openReadStream(entry, (err, readStream) => {
                 if (err) {
-                    e(this.wrapError(err, token.isCancelled));
+                    reject(this.wrapError(err, token.isCancelled));
                 }
                 else {
-                    c(readStream);
+                    resolve(readStream);
                 }
             });
         });
@@ -270,7 +323,7 @@ class Unzip extends cancelable_1.Cancelable {
     async extractEntry(zfile, entry, entryContext, token) {
         const filePath = entryContext.getFilePath();
         const fileDir = path.dirname(filePath);
-        await entryContext.ensureFolder(fileDir);
+        await entryContext.inspectFolder(fileDir);
         const outside = await entryContext.isOutsideTargetFolder(fileDir);
         if (outside) {
             const error = new Error(`Refuse to write file outside "${entryContext.targetFolder}", file: "${filePath}"`);
@@ -279,55 +332,69 @@ class Unzip extends cancelable_1.Cancelable {
         }
         const readStream = await this.openZipFileStream(zfile, entry, token);
         await this.writeEntryToFile(readStream, entry, entryContext, token);
-        zfile.readEntry();
+        this.readNextEntry(zfile, token);
     }
     async writeEntryToFile(readStream, entry, entryContext, token) {
-        let fileStream;
-        token.onCancelled(() => {
-            if (fileStream) {
-                readStream.unpipe(fileStream);
-                fileStream.destroy(this.canceledError());
+        var _a;
+        try {
+            const filePath = entryContext.getFilePath();
+            const mode = this.modeFromEntry(entry);
+            // see https://unix.stackexchange.com/questions/193465/what-file-mode-is-a-symlink
+            const isSymlink = (mode & 0o170000) === 0o120000;
+            if (isSymlink) {
+                entryContext.symlinkFileNames.push(path.resolve(path.join(entryContext.targetFolder, entryContext.decodeEntryFileName)));
             }
-        });
-        return new Promise((c, e) => {
-            try {
-                const filePath = entryContext.getFilePath();
-                readStream.once("error", (err) => {
-                    e(this.wrapError(err, token.isCancelled));
-                });
-                const mode = this.modeFromEntry(entry);
-                // see https://unix.stackexchange.com/questions/193465/what-file-mode-is-a-symlink
-                const isSymlink = (mode & 0o170000) === 0o120000;
-                if (isSymlink) {
-                    entryContext.symlinkFileNames.push(path.resolve(path.join(entryContext.targetFolder, entryContext.decodeEntryFileName)));
+            if (isSymlink && !this.symlinkToFile()) {
+                const linkContent = await this.readStreamContent(readStream, token);
+                if (((_a = this.options) === null || _a === void 0 ? void 0 : _a.safeSymlinksOnly) &&
+                    entryContext.isSymlinkTargetOutsideTargetFolder(linkContent, filePath)) {
+                    const error = new Error(`Dangerous link path was refused : "${entryContext.targetFolder}", file: "${filePath}", target: "${linkContent}". Set safeSymlinksOnly to false to allow writing through this symlink.`);
+                    error.name = "AF_ILLEGAL_TARGET";
+                    throw error;
                 }
-                if (isSymlink && !this.symlinkToFile()) {
-                    let linkContent = "";
-                    readStream.on("data", (chunk) => {
-                        if (chunk instanceof String) {
-                            linkContent += chunk;
-                        }
-                        else {
-                            linkContent += chunk.toString();
-                        }
-                    });
-                    readStream.once("end", () => {
-                        this.createSymlink(linkContent, filePath).then(c, e);
-                    });
+                await entryContext.ensureFolder(path.dirname(filePath));
+                await this.createSymlink(linkContent, filePath);
+            }
+            else {
+                await entryContext.ensureFolder(path.dirname(filePath));
+                const fileStream = (0, node_fs_1.createWriteStream)(filePath, { mode });
+                const pipelinePromise = (0, promises_1.pipeline)(readStream, fileStream);
+                const disposeCancel = token.onCancelled(() => {
+                    fileStream.destroy(this.canceledError());
+                });
+                try {
+                    await pipelinePromise;
                 }
-                else {
-                    fileStream = (0, node_fs_1.createWriteStream)(filePath, { mode });
-                    fileStream.once("close", () => c());
-                    fileStream.once("error", (err) => {
-                        e(this.wrapError(err, token.isCancelled));
-                    });
-                    readStream.pipe(fileStream);
+                finally {
+                    disposeCancel();
                 }
             }
-            catch (error) {
-                e(this.wrapError(error, token.isCancelled));
-            }
+        }
+        catch (error) {
+            throw this.wrapError(error, token.isCancelled);
+        }
+    }
+    async readStreamContent(readStream, token) {
+        let linkContent = "";
+        const readPromise = new Promise((resolve, reject) => {
+            readStream.on("data", (chunk) => {
+                linkContent += typeof chunk === "string" ? chunk : chunk.toString();
+            });
+            readStream.once("end", resolve);
+            readStream.once("error", (err) => {
+                reject(this.wrapError(err, token.isCancelled));
+            });
+        });
+        const disposeCancel = token.onCancelled(() => {
+            readStream.destroy(this.canceledError());
         });
+        try {
+            await readPromise;
+            return linkContent;
+        }
+        finally {
+            disposeCancel();
+        }
     }
     modeFromEntry(entry) {
         const attr = entry.externalFileAttributes >> 16 || 33188;
@@ -335,7 +402,7 @@ class Unzip extends cancelable_1.Cancelable {
             .map((mask) => attr & mask)
             .reduce((a, b) => a + b, attr & 61440 /* S_IFMT */);
     }
-    async createSymlink(linkContent, des) {
+    async createSymlink(linkContent, filePath) {
         let linkType = "file";
         if (process.platform === "win32") {
             if (/\/$/.test(linkContent)) {
@@ -344,7 +411,7 @@ class Unzip extends cancelable_1.Cancelable {
             else {
                 let targetPath = linkContent;
                 if (!path.isAbsolute(linkContent)) {
-                    targetPath = path.join(path.dirname(des), linkContent);
+                    targetPath = path.join(path.dirname(filePath), linkContent);
                 }
                 try {
                     const stat = await fs.stat(targetPath);
@@ -357,7 +424,7 @@ class Unzip extends cancelable_1.Cancelable {
                 }
             }
         }
-        await fs.symlink(linkContent, des, linkType);
+        await fs.symlink(linkContent, filePath, linkType);
     }
     isOverwrite() {
         var _a;

package/lib/zip.d.ts

@@ -1,11 +1,11 @@
 import { Cancelable } from "./cancelable";
 export interface IZipOptions {
     /**
-     * Indicates how to handle when the given path is a symbolic link.
+     * Indicates how to handle the given path when it is a symbolic link.
      *
      * `true`: add the target of the symbolic link to the zip.
      *
-     * `false`: add symbolic link itself to the zip.
+     * `false`: add the symbolic link itself to the zip.
      *
      * The default value is `false`.
      */
@@ -13,7 +13,7 @@ export interface IZipOptions {
     /**
      * Sets the compression level.
      *
-     * 0: the file data will be stored, otherwise, the file data will be deflated.
+     * `0`: the file data will be stored; otherwise, the file data will be deflated.
      *
      * The default value is `6`.
      */
@@ -30,29 +30,44 @@ export declare class Zip extends Cancelable {
     constructor(options?: IZipOptions | undefined);
     private yazlFile;
     private isPipe;
+    private isChunk;
     private zipStream;
     private zipFiles;
     private zipFolders;
     private token;
     /**
-     * Adds a file from the file system at realPath into the zipfile as metadataPath.
+     * Adds a file from the file system at `realPath` to the zip file as `metadataPath`.
      * @param file
-     * @param metadataPath Typically metadataPath would be calculated as path.relative(root, realPath).
+     * @param metadataPath Typically, `metadataPath` would be calculated as `path.relative(root, realPath)`.
      * A valid metadataPath must not start with "/" or /[A-Za-z]:\//, and must not contain "..".
      */
     addFile(file: string, metadataPath?: string): void;
     /**
-     * Adds a folder from the file system at realPath into the zipfile as metadataPath.
+     * Adds a folder from the file system at `realPath` to the zip file as `metadataPath`.
      * @param folder
-     * @param metadataPath Typically metadataPath would be calculated as path.relative(root, realPath).
+     * @param metadataPath Typically, `metadataPath` would be calculated as `path.relative(root, realPath)`.
      * A valid metadataPath must not start with "/" or /[A-Za-z]:\//, and must not contain "..".
      */
     addFolder(folder: string, metadataPath?: string): void;
     /**
-     * Generate zip file.
-     * @param zipFile the zip file path.
+     * Zips the content and returns it as a single Buffer.
+     *
+     * @returns A promise that resolves to the zipped Buffer.
+     */
+    archive(): Promise<Buffer>;
+    /**
+     * Zips the content and saves it directly to the specified file path.
+     *
+     * @param zipFile The absolute or relative path where the .zip file will be created.
+     * @returns A promise that resolves when the file has been fully written.
      */
     archive(zipFile: string): Promise<void>;
+    private prepareArchive;
+    private bindArchiveOutput;
+    private archiveToFile;
+    private archiveToBuffer;
+    private createPromiseSettler;
+    private addQueuedEntries;
     /**
      * Cancel compression.
      * If the cancel method is called after the archive is complete, nothing will happen.
@@ -62,7 +77,7 @@ export declare class Zip extends Cancelable {
     private addFileStream;
     private addSymlink;
     private walkDir;
-    private stopPipe;
+    private stop;
     private followSymlink;
     /**
      * Retrieves the yazl options based on the current settings.