@keep-lts/extract-zip 0.0.0-stage → 2.0.2

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+Security-maintained fork of [`extract-zip`](https://www.npmjs.com/package/extract-zip).
+Only security and compatibility fixes are applied; the public API is unchanged.
+
+## [2.0.2] — 2026-11-07
+
+### Security
+- **Fix CVE-2026-56876 / CVE-2026-19693 / GHSA-jmr9-qjv8-65gv / GHSA-7pqw-9j4j-h8q3 (High, CWE-59 Link Following / CWE-22 Path Traversal).** Symlink entries are resolved the way the operating system will resolve them — from the real directory containing the link, following symlinks that already exist — and rejected unless they land inside the extraction directory. Absolute link targets, and targets with a `..` after a normal segment (which can escape through a symlinked segment), are rejected outright. Before writing a file or creating a link, any symlink already sitting at that path is removed rather than followed.
+  See [SECURITY.md](./SECURITY.md) for the advisory, proof-of-concept, and remediation.
+
+### Notes
+- No public API change; behavior is identical for all legitimate input.
+- Regression tests added in `test/security.test.js`.
+- Drop-in replacement for `extract-zip@2.0.1`.
+
+---
+
+Based on `extract-zip` by max ogden (BSD-2-Clause).

package/LICENSE

@@ -0,0 +1,23 @@
+Copyright (c) 2014 Max Ogden and other contributors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright notice, this
+  list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright notice,
+  this list of conditions and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/SECURITY.md

@@ -0,0 +1,43 @@
+# Security Advisory — extract-zip
+
+## CVE-2026-56876 / CVE-2026-19693 / GHSA-jmr9-qjv8-65gv / GHSA-7pqw-9j4j-h8q3 — Arbitrary file write outside the extraction directory via symlink entries in extract-zip
+
+| | |
+|---|---|
+| **Severity** | High (CWE-59 Link Following / CWE-22 Path Traversal) |
+| **Affected** | `extract-zip` <= 2.0.1 (all published versions) (original package; no upstream fix) |
+| **Fixed in** | `@keep-lts/extract-zip@2.0.2` |
+
+### Summary
+
+extract-zip validated only the parent directory of each archive entry. A malicious zip could (1) create a symlink pointing anywhere on disk (CVE-2026-56876), and (2) follow it with a regular file of the same name, which extract-zip then wrote through the symlink — an arbitrary file write outside the extraction directory (CVE-2026-19693). Any service that extracts user-supplied zips (uploads, plugin/theme installers, CI artefacts, Electron updaters) is exposed.
+
+### Proof of concept
+
+```js
+// zip entries: 'evil' (symlink -> ../../../../home/user/.bashrc), then 'evil' (file: attacker content)
+await require('extract-zip')('evil.zip', { dir: '/srv/uploads/x' })
+// extract-zip 2.0.1 overwrites /home/user/.bashrc
+```
+
+### The fix
+
+Three checks, each covered by a regression test that fails on 2.0.1: (1) every symlink target is resolved against the real filesystem and must land inside the target directory; absolute targets and `x/../y`-style targets are refused, closing bypasses of a purely textual check (e.g. a link through an earlier `d -> .` symlink); (2) an existing symlink at a destination path is removed before writing, never written through; (3) the existing parent-directory check is kept and also guards against cross-drive paths on Windows. Normal archives — files, nested folders, file modes, `__MACOSX` skipping, and relative symlinks that stay inside (as in macOS .app/framework bundles) — extract exactly as before.
+
+### Remediation
+
+Replace the vulnerable dependency with this drop-in fork — no code changes required:
+
+```json
+{
+  "overrides": {
+    "extract-zip": "npm:@keep-lts/extract-zip@^2.0.2"
+  }
+}
+```
+
+Then reinstall and confirm `npm ls extract-zip` resolves to the fork.
+
+### Reporting
+
+Report vulnerabilities in this fork via a private security advisory on the fork repository.

package/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+
+/* eslint-disable no-process-exit */
+
+var extract = require('./')
+
+var args = process.argv.slice(2)
+var source = args[0]
+var dest = args[1] || process.cwd()
+if (!source) {
+  console.error('Usage: extract-zip foo.zip <targetDirectory>')
+  process.exit(1)
+}
+
+extract(source, { dir: dest })
+  .catch(function (err) {
+    console.error('error!', err)
+    process.exit(1)
+  })

package/index.d.ts

@@ -0,0 +1,21 @@
+// Based on the type definitions for extract-zip 1.6
+// Definitions by: Mizunashi Mana <https://github.com/mizunashi-mana>
+// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/e69b58e/types/extract-zip/index.d.ts
+
+import { Entry, ZipFile } from 'yauzl';
+
+declare namespace extract {
+    interface Options {
+        dir: string;
+        defaultDirMode?: number;
+        defaultFileMode?: number;
+        onEntry?: (entry: Entry, zipfile: ZipFile) => void;
+    }
+}
+
+declare function extract(
+  zipPath: string,
+  opts: extract.Options,
+): Promise<void>;
+
+export = extract;

package/index.js

@@ -0,0 +1,245 @@
+const debug = require('debug')('extract-zip')
+// eslint-disable-next-line node/no-unsupported-features/node-builtins
+const { createWriteStream, promises: fs } = require('fs')
+const getStream = require('get-stream')
+const path = require('path')
+const { promisify } = require('util')
+const stream = require('stream')
+const yauzl = require('yauzl')
+
+const openZip = promisify(yauzl.open)
+const pipeline = promisify(stream.pipeline)
+
+// Keep LTS security patch (CVE-2026-19693, CVE-2026-56876):
+// extraction must never read or write outside the target directory.
+
+// True if `target` is `dir` itself or somewhere underneath it (absolute paths).
+function isInside (dir, target) {
+  const relative = path.relative(dir, target)
+  if (relative === '') return true
+  return !relative.split(path.sep).includes('..') && !path.isAbsolute(relative)
+}
+
+// Resolve a symlink's target the way the OS will, starting from the real
+// directory that contains the link, following any symlinks that already exist.
+// Returns null for targets we refuse outright:
+//  - absolute targets (could point anywhere), and
+//  - targets with a `..` after a normal segment (e.g. `x/../y`). The OS applies
+//    `..` after following `x`, so if `x` is (or later becomes) a symlink the
+//    target can escape even though it looks contained on paper.
+async function resolveLinkTarget (realParentDir, link) {
+  if (path.isAbsolute(link) || path.win32.isAbsolute(link) || path.posix.isAbsolute(link)) return null
+  const segments = link.split(/[\\/]+/).filter(s => s !== '' && s !== '.')
+  let seenName = false
+  let current = realParentDir
+  for (const segment of segments) {
+    if (segment === '..') {
+      if (seenName) return null
+      current = path.dirname(current)
+      continue
+    }
+    seenName = true
+    const next = path.join(current, segment)
+    try {
+      current = await fs.realpath(next)
+    } catch (err) {
+      /* istanbul ignore if */
+      if (err.code !== 'ENOENT' && err.code !== 'ENOTDIR') throw err
+      current = next
+    }
+  }
+  return current
+}
+
+// Remove a symlink sitting at `dest` so we replace it instead of writing
+// through it (CVE-2026-19693). Real files and directories are left alone.
+async function removeSymlinkAt (dest) {
+  let stats
+  try {
+    stats = await fs.lstat(dest)
+  } catch (err) {
+    /* istanbul ignore if */
+    if (err.code !== 'ENOENT') throw err
+    return
+  }
+  if (stats.isSymbolicLink()) {
+    debug('removing existing symlink', dest)
+    await fs.unlink(dest)
+  }
+}
+
+class Extractor {
+  constructor (zipPath, opts) {
+    this.zipPath = zipPath
+    this.opts = opts
+  }
+
+  async extract () {
+    debug('opening', this.zipPath, 'with opts', this.opts)
+
+    this.zipfile = await openZip(this.zipPath, { lazyEntries: true })
+    this.canceled = false
+
+    return new Promise((resolve, reject) => {
+      this.zipfile.on('error', err => {
+        this.canceled = true
+        reject(err)
+      })
+      this.zipfile.readEntry()
+
+      this.zipfile.on('close', () => {
+        if (!this.canceled) {
+          debug('zip extraction complete')
+          resolve()
+        }
+      })
+
+      this.zipfile.on('entry', async entry => {
+        /* istanbul ignore if */
+        if (this.canceled) {
+          debug('skipping entry', entry.fileName, { cancelled: this.canceled })
+          return
+        }
+
+        debug('zipfile entry', entry.fileName)
+
+        if (entry.fileName.startsWith('__MACOSX/')) {
+          this.zipfile.readEntry()
+          return
+        }
+
+        const destDir = path.dirname(path.join(this.opts.dir, entry.fileName))
+
+        try {
+          await fs.mkdir(destDir, { recursive: true })
+
+          const canonicalDestDir = await fs.realpath(destDir)
+
+          if (!isInside(this.opts.dir, canonicalDestDir)) {
+            throw new Error(`Out of bound path "${canonicalDestDir}" found while processing file ${entry.fileName}`)
+          }
+
+          await this.extractEntry(entry)
+          debug('finished processing', entry.fileName)
+          this.zipfile.readEntry()
+        } catch (err) {
+          this.canceled = true
+          this.zipfile.close()
+          reject(err)
+        }
+      })
+    })
+  }
+
+  async extractEntry (entry) {
+    /* istanbul ignore if */
+    if (this.canceled) {
+      debug('skipping entry extraction', entry.fileName, { cancelled: this.canceled })
+      return
+    }
+
+    if (this.opts.onEntry) {
+      this.opts.onEntry(entry, this.zipfile)
+    }
+
+    const dest = path.join(this.opts.dir, entry.fileName)
+
+    // Backstop: yauzl already rejects absolute and `..` entry names.
+    /* istanbul ignore if */
+    if (!isInside(this.opts.dir, dest)) {
+      throw new Error(`Out of bound path "${dest}" found while processing file ${entry.fileName}`)
+    }
+
+    // convert external file attr int into a fs stat mode int
+    const mode = (entry.externalFileAttributes >> 16) & 0xFFFF
+    // check if it's a symlink or dir (using stat mode constants)
+    const IFMT = 61440
+    const IFDIR = 16384
+    const IFLNK = 40960
+    const symlink = (mode & IFMT) === IFLNK
+    let isDir = (mode & IFMT) === IFDIR
+
+    // Failsafe, borrowed from jsZip
+    if (!isDir && entry.fileName.endsWith('/')) {
+      isDir = true
+    }
+
+    // check for windows weird way of specifying a directory
+    // https://github.com/maxogden/extract-zip/issues/13#issuecomment-154494566
+    const madeBy = entry.versionMadeBy >> 8
+    if (!isDir) isDir = (madeBy === 0 && entry.externalFileAttributes === 16)
+
+    debug('extracting entry', { filename: entry.fileName, isDir: isDir, isSymlink: symlink })
+
+    const procMode = this.getExtractedMode(mode, isDir) & 0o777
+
+    // always ensure folders are created
+    const destDir = isDir ? dest : path.dirname(dest)
+
+    const mkdirOptions = { recursive: true }
+    if (isDir) {
+      mkdirOptions.mode = procMode
+    }
+    debug('mkdir', { dir: destDir, ...mkdirOptions })
+    await fs.mkdir(destDir, mkdirOptions)
+    if (isDir) return
+
+    debug('opening read stream', dest)
+    const readStream = await promisify(this.zipfile.openReadStream.bind(this.zipfile))(entry)
+
+    if (symlink) {
+      const link = await getStream(readStream)
+      // CVE-2026-56876: a symlink may not point outside the target directory.
+      const realParent = await fs.realpath(path.dirname(dest))
+      const resolved = await resolveLinkTarget(realParent, link)
+      if (resolved === null || !isInside(this.opts.dir, resolved)) {
+        throw new Error(`Out of bound symlink target "${link}" found while processing file ${entry.fileName}`)
+      }
+      debug('creating symlink', link, dest)
+      await removeSymlinkAt(dest)
+      await fs.symlink(link, dest)
+    } else {
+      // CVE-2026-19693: never write through a symlink planted at this path.
+      await removeSymlinkAt(dest)
+      await pipeline(readStream, createWriteStream(dest, { mode: procMode }))
+    }
+  }
+
+  getExtractedMode (entryMode, isDir) {
+    let mode = entryMode
+    // Set defaults, if necessary
+    if (mode === 0) {
+      if (isDir) {
+        if (this.opts.defaultDirMode) {
+          mode = parseInt(this.opts.defaultDirMode, 10)
+        }
+
+        if (!mode) {
+          mode = 0o755
+        }
+      } else {
+        if (this.opts.defaultFileMode) {
+          mode = parseInt(this.opts.defaultFileMode, 10)
+        }
+
+        if (!mode) {
+          mode = 0o644
+        }
+      }
+    }
+
+    return mode
+  }
+}
+
+module.exports = async function (zipPath, opts) {
+  debug('creating target directory', opts.dir)
+
+  if (!path.isAbsolute(opts.dir)) {
+    throw new Error('Target directory is expected to be absolute')
+  }
+
+  await fs.mkdir(opts.dir, { recursive: true })
+  opts.dir = await fs.realpath(opts.dir)
+  return new Extractor(zipPath, opts).extract()
+}

package/package.json

@@ -1,6 +1,100 @@
 {
   "name": "@keep-lts/extract-zip",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "2.0.2",
+  "description": "Security-maintained drop-in fork of extract-zip. Patches CVE-2026-56876 and CVE-2026-19693 (symlink path traversal / arbitrary file write): symlinks may only point inside the target directory, and files are never written through a symlink. Original API unchanged.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "bin": {
+    "extract-zip": "cli.js"
+  },
+  "scripts": {
+    "ava": "ava",
+    "coverage": "nyc ava",
+    "lint": "yarn lint:js && yarn lint:ts && yarn tsd",
+    "lint:js": "eslint .",
+    "lint:ts": "eslint --config .eslintrc.typescript.js --ext .ts .",
+    "test": "node --test test/security.test.js",
+    "tsd": "tsd"
+  },
+  "files": [
+    "cli.js",
+    "index.d.ts",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "author": "max ogden",
+  "license": "BSD-2-Clause",
+  "repository": "keep-lts/extract-zip",
+  "keywords": [
+    "unzip",
+    "zip",
+    "extract",
+    "cve-2026-56876",
+    "cve-2026-19693",
+    "security",
+    "patch",
+    "lts",
+    "fork",
+    "cwe-59-link-following-/-cwe-22-path-traversal"
+  ],
+  "engines": {
+    "node": ">= 10.17.0"
+  },
+  "dependencies": {
+    "debug": "^4.1.1",
+    "get-stream": "^5.1.0",
+    "yauzl": "^2.10.0"
+  },
+  "optionalDependencies": {
+    "@types/yauzl": "^2.9.1"
+  },
+  "devDependencies": {
+    "@typescript-eslint/eslint-plugin": "^3.2.0",
+    "@typescript-eslint/parser": "^3.2.0",
+    "ava": "^3.5.1",
+    "eslint": "^7.2.0",
+    "eslint-config-standard": "^14.1.1",
+    "eslint-plugin-ava": "^10.2.0",
+    "eslint-plugin-import": "^2.20.1",
+    "eslint-plugin-node": "^11.0.0",
+    "eslint-plugin-promise": "^4.2.1",
+    "eslint-plugin-standard": "^4.0.1",
+    "fs-extra": "^9.0.0",
+    "husky": "^4.2.3",
+    "lint-staged": "^10.0.9",
+    "nyc": "^15.0.0",
+    "tsd": "^0.11.0",
+    "typescript": "^3.8.3"
+  },
+  "eslintConfig": {
+    "extends": [
+      "eslint:recommended",
+      "plugin:ava/recommended",
+      "plugin:import/errors",
+      "plugin:import/warnings",
+      "plugin:node/recommended",
+      "plugin:promise/recommended",
+      "standard"
+    ]
+  },
+  "husky": {
+    "hooks": {
+      "pre-commit": "lint-staged"
+    }
+  },
+  "lint-staged": {
+    "*.js": "yarn lint:js --fix",
+    "*.ts": "yarn lint:ts --fix"
+  },
+  "contributors": [
+    "Keep LTS (security maintenance fork)"
+  ],
+  "bugs": {
+    "url": "https://github.com/keep-lts/extract-zip/issues"
+  },
+  "homepage": "https://github.com/keep-lts/extract-zip",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/readme.md

@@ -0,0 +1,75 @@
+# @keep-lts/extract-zip
+
+> Security-maintained, drop-in fork of [`extract-zip`](https://www.npmjs.com/package/extract-zip).
+
+> [!IMPORTANT]
+> **Unofficial security-maintenance fork.** The original `extract-zip` has no fix for
+> **CVE-2026-56876 / CVE-2026-19693 / GHSA-jmr9-qjv8-65gv / GHSA-7pqw-9j4j-h8q3** (High). This fork applies a minimal, tested patch and keeps the
+> public API byte-for-byte compatible. Adopt with zero code changes via npm `overrides`:
+>
+> ```json
+> { "overrides": { "extract-zip": "npm:@keep-lts/extract-zip@^2.0.2" } }
+> ```
+>
+> See [SECURITY.md](./SECURITY.md) and [CHANGELOG.md](./CHANGELOG.md). Original functionality
+> and attribution preserved under the BSD-2-Clause license.
+
+---
+
+# extract-zip
+
+Unzip written in pure JavaScript. Extracts a zip into a directory. Available as a library or a command line program.
+
+Uses the [`yauzl`](http://npmjs.org/yauzl) ZIP parser.
+
+[![NPM](https://nodei.co/npm/extract-zip.png?global=true)](https://npm.im/extract-zip)
+[![Uses JS Standard Style](https://cdn.jsdelivr.net/gh/standard/standard/badge.svg)](https://github.com/standard/standard)
+[![Build Status](https://github.com/maxogden/extract-zip/workflows/CI/badge.svg)](https://github.com/maxogden/extract-zip/actions?query=workflow%3ACI)
+
+## Installation
+
+Make sure you have Node 10 or greater installed.
+
+Get the library:
+
+```
+npm install extract-zip --save
+```
+
+Install the command line program:
+
+```
+npm install extract-zip -g
+```
+
+## JS API
+
+```javascript
+const extract = require('extract-zip')
+
+async function main () {
+  try {
+    await extract(source, { dir: target })
+    console.log('Extraction complete')
+  } catch (err) {
+    // handle any errors
+  }
+}
+```
+
+### Options
+
+- `dir` (required) - the path to the directory where the extracted files are written
+- `defaultDirMode` - integer - Directory Mode (permissions), defaults to `0o755`
+- `defaultFileMode` - integer - File Mode (permissions), defaults to `0o644`
+- `onEntry` - function - if present, will be called with `(entry, zipfile)`, entry is every entry from the zip file forwarded from the `entry` event from yauzl. `zipfile` is the `yauzl` instance
+
+Default modes are only used if no permissions are set in the zip file.
+
+## CLI Usage
+
+```
+extract-zip foo.zip <targetDirectory>
+```
+
+If not specified, `targetDirectory` will default to `process.cwd()`.

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.