node-stream-zip - npm Package Compare versions

Comparing version 1.3.8 to 1.4.0

node_stream_zip.js

@@ -339,2 +339,5 @@ /**
                 entry.read(buffer, bufferPos);
+                if (!config.skipEntryNameValidation) {
+                    entry.validateName();
+                }
                 if (entries)
@@ -722,2 +725,8 @@ entries[entry.name] = entry;
 
+ZipEntry.prototype.validateName = function() {
+    if (/\\|^\w+:|^\/|(^|\/)\.\.(\/|$)/.test(this.name)) {
+        throw new Error('Malicious entry: ' + this.name);
+    }
+};
+
 ZipEntry.prototype.readExtra = function(data, offset) {
@@ -724,0 +733,0 @@ var signature, size, maxPos = offset + this.extraLen;

package.json

 {
   "name": "node-stream-zip",
-  "version": "1.3.8",
+  "version": "1.4.0",
   "description": "node.js library for reading and extraction of ZIP archives",
@@ -5,0 +5,0 @@ "keywords": [

README.md

@@ -6,10 +6,10 @@ # node-stream-zip [![Build status](https://travis-ci.org/antelle/node-stream-zip.svg?branch=master)](https://travis-ci.org/antelle/node-stream-zip)
 
-- it never loads entire archive into memory, everything is read by chunks  
-- large archives support  
-- all operations are non-blocking, no sync i/o  
-- fast initialization  
-- no dependencies, no binary addons  
+- it never loads entire archive into memory, everything is read by chunks
+- large archives support
+- all operations are non-blocking, no sync i/o
+- fast initialization
+- no dependencies, no binary addons
 - decompression with built-in zlib module
-- deflate, deflate64, sfx, macosx/windows built-in archives  
-- ZIP64 support  
+- deflate, deflate64, sfx, macosx/windows built-in archives
+- ZIP64 support
 
@@ -22,45 +22,102 @@ # Installation
 
+Open a zip file
 ```javascript
-var StreamZip = require('node-stream-zip');  
-var zip = new StreamZip({  
-    file: 'archive.zip',  
-    storeEntries: true    
+const StreamZip = require('node-stream-zip');
+const zip = new StreamZip({
+    file: 'archive.zip',
+    storeEntries: true
 });
-zip.on('error', function(err) { /*handle*/ });
-zip.on('ready', function() {
+
+// Handle errors
+zip.on('error', err => { /*handle*/ });
+```
+
+List entries
+```javascript
+zip.on('ready', () => {
     console.log('Entries read: ' + zip.entriesCount);
+    for (const entry of Object.values(entries)) {
+        const desc = entry.isDirectory ? 'directory' : `${entry.size} bytes`;
+        console.log(`Entry ${entry.name}: ${desc}`);
+    }
+    // Do not forget to close the file once you're done
+    zip.close()
+});
+```
+
+Stream one entry to stdout
+```javascript
+zip.on('ready', () => {
     // stream to stdout
-    zip.stream('node/benchmark/net/tcp-raw-c2s.js', function(err, stm) {
+    zip.stream('path/inside/zip.txt', (err, stm) => {
         stm.pipe(process.stdout);
+        stm.on('end', () => zip.close());
     });
-    // extract file
-    zip.extract('node/benchmark/net/tcp-raw-c2s.js', './temp/', function(err) {
-        console.log('Entry extracted');
+});
+```
+
+Extract one file to disk
+```javascript
+zip.on('ready', () => {
+    zip.extract('path/inside/zip.txt', './extracted.txt', err => {
+        console.log(err ? 'Extract error' : 'Extracted');
         zip.close();
     });
-    // extract folder
-    zip.extract('node/benchmark/', './temp/', function(err, count) {
-        console.log('Extracted ' + count + ' entries');
+});
+```
+
+Extract a folder from archive to disk
+```javascript
+zip.on('ready', () => {
+    fs.mkdirSync('extracted');
+    zip.extract('path/inside/zip/', './extracted', err => {
+        console.log(err ? 'Extract error' : 'Extracted');
         zip.close();
     });
-    // extract all
-    zip.extract(null, './temp/', function(err, count) {
-        console.log('Extracted ' + count + ' entries');
+});
+```
+
+Extract everything
+```javascript
+zip.on('ready', () => {
+    fs.mkdirSync('extracted');
+    zip.extract(null, './extracted', (err, count) => {
+        console.log(err ? 'Extract error' : `Extracted ${count} entries`);
         zip.close();
     });
-    // read file as buffer in sync way
-    var data = zip.entryDataSync('README.md');
 });
-zip.on('extract', function(entry, file) {
-    console.log('Extracted ' + entry.name + ' to ' + file);
+```
+
+Read a file as buffer in sync way
+```javascript
+zip.on('ready', () => {
+    const data = zip.entryDataSync('path/inside/zip.txt');
+    zip.close();
 });
-zip.on('entry', function(entry) {
-    // called on load, when entry description has been read
-    // you can already stream this entry, without waiting until all entry descriptions are read (suitable for very large archives)
-    console.log('Read entry ', entry.name);
+```
+
+When extracting a folder, you can listen to `extract` event
+```javascript
+zip.on('extract', (entry, file) => {
+    console.log(`Extracted ${entry.name} to ${file}`);
 });
 ```
 
-If you pass `storeEntries: true` to constructor, you will be able to access entries inside zip archive with:
+`entry` event is generated for every entry during loading
+```javascript
+zip.on('entry', entry => {
+    // you can already stream this entry,
+    // without waiting until all entry descriptions are read (suitable for very large archives)
+    console.log(`Read entry ${entry.name}`);
+});
+```
 
+# Options
+
+You can pass these options to the constructor
+- `storeEntries: true` - you will be able to work with entries inside zip archive, otherwise the only way to access them is `entry` event
+- `skipEntryNameValidation: true` - by default, entry name is checked for malicious characters, like `../` or `c:\123`, pass this flag to disable validation errors
+
+# Methods
+
 - `zip.entries()` - get all entries description
@@ -70,2 +127,3 @@ - `zip.entry(name)` - get entry description by name
 - `zip.entryDataSync(entry)` - get entry data in sync way
+- `zip.close()` - cleanup after all entries have been read, streamed, extracted, and you don't need the archive
 
@@ -80,3 +138,3 @@ # Building
 - [utf8](https://github.com/rubyzip/rubyzip/wiki/Files-with-non-ascii-filenames) file names
-- AES encrypted files  
+- AES encrypted files
 
@@ -83,0 +141,0 @@ # Contributors

No alert changes

Improved metrics

Total package byte prevSize

39219

increased by3.83%

Lines of code

892

increased by0.9%

Number of lines in readme file

140

increased by70.73%

No dependency changes