The central directory is the only authority a DOCX reader has
A zip archive describes every entry twice: once in the central directory at the end of the file, and once in a local header that sits in front of the entry's data. Nothing in the format makes the two copies agree. So a reader that trusts whichever description it consults first can be shown one document, while a different reader consulting the other copy sees something else, from the same bytes, with the same checksum, under the same file name.
For most tooling that is a curiosity. For a reader whose output goes to an AI screener it is the whole problem. The screener's input is text, and the question a reviewer eventually asks is "what did the model actually read?" If the archive admits two readings, that question has two answers, and the audit trail is worthless before the first word of text comes out. So in screenfence we took the position that a document which reads two ways is a document nobody should read: readZip names one description authoritative and refuses, by code and part name, every place the archive disagrees with itself.
The constraint: repair is not available to us#
The tempting posture is leniency. Every unzip utility in wide use is lenient, because a user who double-clicks an archive wants their files, and a local header that disagrees with the directory is usually just a tool writing sloppy bytes. Lenient readers pick a side, often silently, and often differently from each other.
We cannot pick a side quietly, because the thing downstream of us is not a user looking at a folder. It is an automated decision. A reader that resolves ambiguity by preference is a reader whose behaviour you have to reverse-engineer to understand a screening result. A reader that refuses ambiguity has one behaviour, and it fits in a sentence.
One authority, checked from the end backwards#
readZip starts where the format says the truth lives. findEocd scans backwards for an EOCD_SIGNATURE whose declared comment length matches its own position, since a signature pattern that turns up earlier in the compressed data is not the record, because the real record's comment field has to account for exactly the bytes that follow it. Before anything is parsed, the archive is refused if a ZIP64_LOCATOR_SIGNATURE precedes the record, if it claims a second disk, if the entry counts disagree with each other, or if it carries zip64 sentinels.
readCentral then walks totalEntries headers and refuses, per entry, everything that would make a part unreadable or ambiguous rather than merely unusual:
if ((flags & ENCRYPTION_FLAGS) !== 0) {
refuse('encrypted-entry', 'an encryption flag is set', name);
}
if (
versionNeeded >= ZIP64_VERSION ||
diskStart === SENTINEL_16 ||
compressedSize === SENTINEL_32 ||
uncompressedSize === SENTINEL_32 ||
localOffset === SENTINEL_32 ||
hasZip64Extra(reader, nameAt + nameLength, extraLength)
) {
refuse('zip64-marker', 'the entry is marked zip64', name);
}
if (method !== METHOD_STORE && method !== METHOD_DEFLATE) {
refuse('unsupported-method', `method ${method} is neither stored nor deflated`, name);
}An empty name and trailing bytes after the last directory header are both bad-central-directory. The entries that survive this pass are the archive's one description of itself.
The local headers are then not consulted for facts. They are checked for agreement:
if (!sameBytes(reader.bytes.subarray(nameAt, nameAt + nameLength), entry.nameBytes)) {
refuse('local-name-mismatch', 'the local header names another part', entry.name);
}
if (method !== entry.method) {
refuse('bad-local-header', 'the method differs from the central directory', entry.name);
}
if (
(flags & FLAG_DATA_DESCRIPTOR) === 0 &&
(compressedSize !== entry.compressedSize || uncompressedSize !== entry.uncompressedSize)
) {
refuse('declared-size-mismatch', 'the local header declares other sizes', entry.name);
}The name comparison runs on raw bytes rather than decoded strings, because two different byte sequences that decode to the same name are still two different names as far as the archive is concerned.
The size comparison has one deliberate hole. When FLAG_DATA_DESCRIPTOR is set, the local header is allowed to declare nothing, and the sizes follow the data instead. There is no honest comparison to make there, so we do not fake one. The check moves to the only place where it can still be made against the authority, which is after extraction.
One part, folded once#
OPC part names are case-insensitive. word/document.xml and WORD/Document.xml are one part to a consumer and two entries to the archive, so that is a second way for a package to read two ways: a reader that picks the first match and a reader that picks the last match disagree about the document.
// OPC part names are case-insensitive: two entries folding together are two readings.
if (!name.endsWith('/')) {
const key = name.toLowerCase();
if (folded.has(key)) {
refuse('duplicate-part-name', 'two part names are equal under case folding', name);
}
folded.add(key);
}The interesting part is not the refusal, it is that findPart folds case the same way. A duplicate check and a lookup that disagreed about what counts as one name would reopen the hole from the other end: the check would pass two entries and the lookup would choose between them. Because both fold with toLowerCase, the test that findPart(parts, 'WORD/Document.XML') resolves to word/document.xml is also a test that the duplicate rule covers everything the lookup can reach. That matters more than it looks, because the main document part is found through _rels/.rels rather than assumed to be word/document.xml, so the name we search for comes out of the package itself.
No byte belongs to two parts#
Name agreement is not enough. Offsets can be arranged so that one region of the file sits inside two entries, which makes a single blob readable as two different parts depending on which header you enter through. Each entry's data also has to stop before the directory it was described in:
const dataStart = nameAt + nameLength + extraLength;
const dataEnd = dataStart + entry.compressedSize;
if (dataEnd > cdOffset) {
refuse('bad-local-header', 'the entry data overruns the central directory', entry.name);
}and then the located entries are sorted by headerStart and checked pairwise, so overlapping-entries is raised when one entry's dataEnd passes the next entry's headerStart. After refuseOverlaps returns, every byte the reader will inflate belongs to exactly one part.
The bytes out must be the bytes declared#
The last disagreement is between the declaration and the content. After extraction, the byte count has to equal uncompressedSize and crc32 has to equal the recorded crc, or the part is a declared-size-mismatch or a crc-mismatch. This is where the data-descriptor carve-out gets paid back: an entry that declared nothing locally still has to produce exactly what the central directory said it would.
We hold the checksum implementation to an independent one in the test suite rather than trusting a table-driven routine to be right:
for (const sample of ['', 'a', PART, DOCUMENT, 'x'.repeat(1000)]) {
assert.equal(crc32(encoder.encode(sample)), crc32Bitwise(encoder.encode(sample)));
}A bad crc32 would not fail loudly. It would turn the strongest content check in the reader into a source of false refusals, or worse, pass a tampered part whose crc collides with the table's mistake.
What it costs to run#
Three things, and they are worth naming plainly.
First, we refuse archives that other tools open. Some writers emit sloppy local headers, we do not repair them, and a user whose file is refused gets a code and a part name instead of their text. We think that is the correct trade for an automated screening path, and it is why refusals are specific: ZipRefusal carries the code and the part, so an operator can tell duplicate-part-name in a cover letter apart from crc-mismatch in a theme part without reading hex.
Second, refusing requires a test harness that can write archives no real tool would write. test/helpers/zipwriter.ts exists for exactly that. buildZip takes per-field overrides (localName, localMethod, localCompressedSize, eocdSignature, diskNumber, entriesOnDisk, zip64Locator, extra), so each refusal case is one small, readable archive built to disagree with itself in one specific way. Writing broken zips by hand is the only way to know the checks fire.
Third, the limits have to be published rather than tuned in private. The defaults are pinned by a test (at most 256 entries, 32 MiB inflated, 200× expansion per entry, with a 64 KiB floor below which the ratio is not judged) because a compression-ratio rule applied to tiny parts rejects ordinary documents.
The posture repeats in the layers above, and that repetition is deliberate: readXml refuses a DOCTYPE, an entity reference, an unbound prefix, a document element outside WordprocessingML and nesting past 64 levels; CascadeRefusal refuses a package with no _rels/.rels, no internal relationship naming the main part, and a w:basedOn chain that returns to a style it already visited. Each layer names an authority and declines to guess when the input contradicts it. One archive, one reading, or no reading at all.