v2.8.59

What's Changed in v2.8.59

New features

• New ZipReader#warnings property and warnings property on entries. They report non-fatal anomalies noticed while reading, as an array of { reason, filename? } objects deduplicated by reason. ZipReader#warnings is replaced on each getEntries() call and collects the archive-level observations: an unsorted central directory, an unknown "version needed to extract", the compressed patched data bit, a malformed extra field, unknown zip64 extensible data, and a wrapped 16-bit entry count. The entry-level warnings property is set by getData() and collects the local file header observations. The checks controlled by the strictness option deposit a warning with the same reason when a lower strictness tolerates what "strict" rejects: appended or prepended data, trailing central directory data, duplicate filenames, a mismatched zip64 end of central directory record, and local file header mismatches. The warnings only report bytes the parse already read, so enabling nothing costs no additional I/O. The reasons are exported as 14 WARNING_* constants
• New isZipFile() function. It returns true if the data looks like a zip file, i.e. if ZipReader#getEntries called on the same data would locate the archive structure. It runs the same end-anchored search as ZipReader and verifies that a central directory record is stored where the end of central directory record points, without parsing the entries. The strictness and maxAppendedDataSize options control the tolerated appended data with the same semantics and defaults as ZipReader
• New centralExtraField option of ZipWriter#add. It sets an extra field written only in the central directory record, complementing the localExtraField option which targets the local file header and the extraField option which targets both

Behavior changes

• Leading and trailing whitespace in entry names is now preserved by ZipWriter#add instead of being silently trimmed. The zip specification does not restrict whitespace in filenames; note that Windows filesystems cannot represent a trailing space or dot in a name
• Unclaimed bytes lying between the last central directory record and the end of central directory record are now detected, even when the declared central directory size matches the records. The "strict" strictness rejects such archives with the ERR_AMBIGUOUS_ARCHIVE error and the lower strictness levels deposit the "trailing central directory data" warning. These bytes were previously accepted silently at every strictness level, although the gap can hide records that other readers interpret, e.g. an unadvertised zip64 end of central directory record, and Info-ZIP and 7-Zip both flag such files. The check is skipped when the central directory is encrypted, because the plaintext is legitimately shorter than the stored data

Tests and continuous integration

• A new test suite covers the warnings: each reason is triggered by byte surgery on a well-formed zip file and asserted both as a warning at the tolerant levels and as a rejection at the levels that make the corresponding check throw
• New regression tests lock the preserved whitespace in entry names, the isZipFile() probe, the centralExtraField option, and the detection of unclaimed bytes before the end of central directory record

Credits

• Claude (Fable 5) contributed to every change listed above