rules/security.md
GitHubHandling untrusted ZIP archives
Zip Slip (path traversal)
zipEntry.name is returned verbatim. It is never normalized or rejected, even
when it contains .., a leading /, a drive letter, or backslashes. ZipFile and ZipBuffer
never write to disk, so the extraction code you write must check every path:
import { resolve, sep } from 'node:path';
function safeTarget(root, name) { // root must already be absolute and resolved
const target = resolve(root, name);
return target === root || target.startsWith(root + sep) ? target : null;
}
- Skip
entry.isSymlinkentries, or validate their target (await entry.content()holds the link text) with the same check. A link that escapes the destination can redirect a later write. - The central directory is authoritative. A local header that disagrees with it is ignored, so
"ZIP confusion" archives cannot make
namedisagree with the content you read. - For names that are neither UTF-8 nor CP437, decode
entry.nameBufferyourself.
Zip bombs
content()checks the declared uncompressed size againstmaxSizebefore it allocates anything. The default isgetMaxZipContentSize()(256 MiB). Lower it for each call (content({ maxSize })) or for the whole process (setMaxZipContentSize(n)).contentIterator()andzipFile.stream()have no cap by default. PassmaxSize. Each chunk is bounded so the total never exceeds the declared size.- Bound the total too: sum
entry.sizeover the entries and checkzip.size(the number of entries) before extracting. The per-entry limits do not cap the aggregate. - An oversized central directory makes
ZipFile.openthrowERR_ZIP_ARCHIVE_TOO_LARGE.
Integrity
verifydefaults totrue.content()checks CRC-32 before it returns, and rejects withERR_ZIP_ENTRY_CORRUPT.contentIterator()can only verify at the end: it yields every chunk and then throws. Write the chunks to a temporary file and rename it on success, or usecontent().rawContent*()(v27+) returns the stored bytes without any CRC check.
Durability of in-place edits
ZipFile add, addEntry and delete rewrite the central directory in place, so they are not
crash-atomic. A failed write (a full disk, or a killed process) can leave the file unreadable.
If durability matters, copy the file first, or compact() it into a new file and rename() the result.
Untrusted input checklist
- Prefer
ZipFile.open(lazy) for files andZipBufferfor a body already in memory. CatchERR_ZIP_INVALID_ARCHIVEandERR_ZIP_UNSUPPORTED_FEATURE. - Check the entry count and the sum of
entry.sizeagainst your limits. - Resolve every name under the destination root. Skip symlinks, or validate their targets.
- Read with
content({ maxSize }), or stream withcontentIterator({ maxSize })into a temporary file that you rename after the iterator completes. - Do not apply the archive's
modebits blindly, because setuid, setgid and sticky bits are included.