@vibe-agent-toolkit/utils 0.2.0-rc.11 → 0.2.0-rc.12

package/dist/archive/tar-reader.js

@@ -0,0 +1,173 @@
+/**
+ * The tar reader: every entry of a tar stream (gzipped or plain), parsed in memory and bounded
+ * while it is parsed. One of the two files in VAT that import an archive library.
+ */
+import { constants as zlibConstants, gunzipSync } from 'node:zlib';
+import { Parser } from 'tar';
+import { isVatError } from '../errors/vat-error.js';
+import { ARCHIVE_REFUSED_CODE, entryNameOf } from './entries.js';
+import { archiveBytesCap, tooLarge, tooManyEntries, unreadableArchive, unsupportedEntry } from './limits.js';
+/** The tar entry types that are a regular file, and the ones that are a directory. */
+const FILE_TYPES = new Set(['File', 'OldFile', 'ContiguousFile']);
+const DIRECTORY_TYPES = new Set(['Directory', 'GNUDumpDir']);
+/**
+ * What an entry is. One the tar library would SKIP — a sparse file, a continuation, a tape volume
+ * header, a type byte no tar defines, a metadata record too large to read — is `other`: dropping
+ * it silently would install the archive without one of its entries, where `tar xf` writes a file.
+ */
+function kindOf(entry) {
+    if (entry.ignore)
+        return 'other';
+    const type = entry.type;
+    if (FILE_TYPES.has(type))
+        return 'file';
+    if (DIRECTORY_TYPES.has(type))
+        return 'directory';
+    if (type === 'SymbolicLink')
+        return 'link';
+    if (type === 'Link')
+        return 'hardlink';
+    return 'other';
+}
+/** Any of the owner, group or other execute bits. */
+const EXECUTE_BITS = 0o111;
+/** Whether zlib refused to inflate past the cap it was given. */
+function exceededOutputCap(error) {
+    return error.code === 'ERR_BUFFER_TOO_LARGE';
+}
+/** Whether zlib ran out of input before the stream ended: a gzip stream cut short. */
+function endedEarly(error) {
+    return error.code === 'Z_BUF_ERROR';
+}
+/**
+ * Inflate `bytes` bounded by `limits`; a stream cut short inflates as far as it goes (a sync
+ * flush), so the tar layer can name the entry the cut fell in — the answer a plain tarball cut
+ * inside an entry gets. A gzip stream cut on an entry boundary is still refused, naming the last
+ * entry: gzip records where it ends. A PLAIN tar cut on an entry boundary is not — the reader does
+ * not require tar's end-of-archive blocks, so nothing marks it incomplete (documented under
+ * `INPUT_UNREADABLE` in `docs/validation-codes.md`).
+ */
+function inflated(bytes, archive, limits) {
+    const maxOutputLength = archiveBytesCap(limits);
+    try {
+        return { stream: gunzipSync(bytes, { maxOutputLength }), truncated: false };
+    }
+    catch (error) {
+        if (exceededOutputCap(error))
+            throw tooLarge(archive, limits, error);
+        if (!endedEarly(error))
+            throw unreadableArchive(archive, `it is not a gzip stream that inflates (${String(error)})`, error);
+    }
+    try {
+        return { stream: gunzipSync(bytes, { maxOutputLength, finishFlush: zlibConstants.Z_SYNC_FLUSH }), truncated: true };
+    }
+    catch (error) {
+        throw exceededOutputCap(error) ? tooLarge(archive, limits, error) : unreadableArchive(archive, `it is not a gzip stream that inflates (${String(error)})`, error);
+    }
+}
+/** The magic numbers a compressed stream begins with. */
+const GZIP_MAGIC = [0x1f, 0x8b];
+const ZSTD_MAGIC = [0x28, 0xb5, 0x2f, 0xfd];
+const beginsWith = (bytes, magic) => magic.every((byte, index) => bytes[index] === byte);
+/**
+ * The tar stream itself: `bytes` inflated when they are gzip (by their magic number), bounded by
+ * what an archive within `limits` can be — so a stream that inflates without end is refused at
+ * the bound, never held.
+ *
+ * ONE layer, and it is this one. The tar library sniffs whatever it is handed for a gzip or a zstd
+ * magic of its own and inflates it with no bound of VAT's, so a stream that is still compressed
+ * here — a tarball gzipped twice, a zstd stream — is refused, never passed on.
+ */
+function tarStream(bytes, archive, limits) {
+    let read = { stream: bytes, truncated: false };
+    if (beginsWith(bytes, GZIP_MAGIC)) {
+        read = inflated(bytes, archive, limits);
+        if (beginsWith(read.stream, GZIP_MAGIC))
+            throw unreadableArchive(archive, 'it is compressed more than once (a gzip stream inside a gzip stream), and VAT inflates one layer');
+    }
+    if (beginsWith(read.stream, ZSTD_MAGIC))
+        throw unreadableArchive(archive, 'it is a zstd stream, and VAT reads a tar archive plain or gzipped');
+    return read;
+}
+/** One parse of a tar stream, holding the entries and the bounds they are held to. */
+class TarListing {
+    records = [];
+    /** The first thing the parser said is wrong with the stream. */
+    problem;
+    #bytes = 0;
+    #archive;
+    #limits;
+    constructor(archive, limits) {
+        this.#archive = archive;
+        this.#limits = limits;
+    }
+    /** Take one entry at its header — bounded there, before its body is read. */
+    take = (entry) => {
+        const kind = kindOf(entry);
+        const size = kind === 'file' ? entry.size : 0;
+        this.#bytes += size;
+        if (this.records.length >= this.#limits.maxEntries)
+            throw tooManyEntries(this.#archive, this.#limits);
+        if (this.#bytes > this.#limits.maxBytes)
+            throw tooLarge(this.#archive, this.#limits);
+        // The body arrives as slices of the stream this module holds: kept, not copied. A skipped entry's body is the library's to drain.
+        const chunks = [];
+        if (!entry.ignore)
+            entry.on('data', (chunk) => chunks.push(chunk));
+        this.records.push({
+            name: entryNameOf(entry.path),
+            kind,
+            size,
+            executable: ((entry.mode ?? 0) & EXECUTE_BITS) !== 0,
+            read: () => (chunks.length === 1 && chunks[0] !== undefined ? chunks[0] : Buffer.concat(chunks)),
+        });
+    };
+    warn = (_code, message) => {
+        this.problem ??= message;
+    };
+}
+/**
+ * Every entry of the tar archive `bytes`, in archive order, each as the archive spells it ({@link entryNameOf}) — links,
+ * devices and unsafe names included: listing judges nothing. Synchronous and in memory.
+ *
+ * @param bytes - The archive, gzipped or plain
+ * @param archive - What the operator named, for a refusal's message
+ * @param limits - The bounds the archive is held to as it is parsed
+ * @throws ArchiveRefusedError `unreadable` for bytes that are no tar archive; `unsupported`, naming
+ *   the entry, for one whose entry is cut short; `too-many-entries` or `too-large` for one past `limits`
+ */
+export function readTar(bytes, archive, limits) {
+    const listing = new TarListing(archive, limits);
+    const { stream, truncated } = tarStream(bytes, archive, limits);
+    // The library is told to inflate nothing: `tarStream` has refused every stream it would sniff as compressed.
+    const parser = new Parser({ onReadEntry: listing.take, onwarn: listing.warn, brotli: false, zstd: false });
+    parser.on('ignoredEntry', listing.take);
+    try {
+        // In memory the parse is synchronous: every entry has been taken, whole, when `end` returns.
+        parser.end(stream);
+    }
+    catch (error) {
+        // A bound `take` raised is the refusal; anything else is the library giving up on the bytes.
+        if (isVatError(error, ARCHIVE_REFUSED_CODE))
+            throw error;
+        throw unreadableArchive(archive, `it is not a tar archive VAT can read (${String(error)})`, error);
+    }
+    // Before the parser's own complaint, which a cut-short body also raises: an entry whose header
+    // parsed is in a tarball, one that does not hold what it declares — `unsupported`, not `unreadable`.
+    for (const record of listing.records) {
+        if (record.kind === 'file' && record.read().length !== record.size) {
+            throw unsupportedEntry(archive, record.name, `declares ${record.size} bytes and is cut short at ${record.read().length}`);
+        }
+    }
+    // Cut short in the gzip layer on an entry boundary: every entry parsed whole, and the stream
+    // still ended early — the tarball is cut short after its last entry.
+    const last = listing.records.at(-1);
+    if (truncated && last !== undefined)
+        throw unsupportedEntry(archive, last.name, 'is the last entry before the gzip stream is cut short');
+    if (truncated)
+        throw unreadableArchive(archive, 'it is a gzip stream cut short before any tar entry');
+    if (listing.problem !== undefined)
+        throw unreadableArchive(archive, `it is not a tar archive VAT can read (${listing.problem})`);
+    return listing.records;
+}
+//# sourceMappingURL=tar-reader.js.map

package/dist/archive/tar-reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tar-reader.js","sourceRoot":"","sources":["../../src/archive/tar-reader.ts"],"names":[],"mappings":"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"}

package/dist/archive/zip-reader.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The ZIP reader and writer: every entry of a ZIP's central directory, each inflated only when
+ * asked, and the one ZIP VAT writes. One of the two files in VAT that import an archive library.
+ */
+import { type ArchiveLimits } from './entries.js';
+import type { ArchiveRecord } from './records.js';
+/**
+ * One central-directory record as VAT reads it off the bytes: the name, and every field the ZIP
+ * library extracts the entry by — where its local header is, the two sizes, and the method.
+ */
+interface CentralRecord {
+    readonly name: Buffer;
+    readonly offset: number;
+    readonly compressedSize: number;
+    readonly size: number;
+    readonly method: number;
+}
+/** The fields of a {@link CentralRecord} beside its name, as the ZIP library's entry header carries them. */
+declare const EXTENT_FIELDS: readonly ["offset", "compressedSize", "size", "method"];
+/**
+ * The second lock on "which directory is this archive's": the ZIP library's OWN answer, held to
+ * VAT's. Whatever the two scans do, the entries the library built must be the entries VAT read
+ * off the bytes — the same count, the same names in the same order, and each extracted by the
+ * same local-header offset, sizes and method — or the archive is refused. A differential neither
+ * reading anticipated lands here instead of in an install: so does a per-entry ZIP64 extra field,
+ * which the library reads a size or an offset from wherever the central record holds 0xFFFFFFFF.
+ *
+ * @throws ArchiveRefusedError `unsupported`
+ */
+export declare function sameDirectory(archive: string, records: readonly CentralRecord[], entries: ReadonlyArray<{
+    readonly rawEntryName: Buffer;
+    readonly header: Readonly<Record<(typeof EXTENT_FIELDS)[number], number>>;
+}>): void;
+/**
+ * Every entry of the ZIP archive `bytes`, in central-directory order, each as the archive spells
+ * it — links, devices and unsafe names included: listing judges nothing. Nothing is inflated
+ * until a record is read, and the reader caps each inflation at the size the entry declares.
+ *
+ * @param bytes - The archive
+ * @param archive - What the operator named, for a refusal's message
+ * @param limits - The bounds the archive is held to, by what its entries declare
+ * @throws ArchiveRefusedError `unreadable` for bytes that are no ZIP archive at all (they hold
+ *   neither a local-file-header nor an end-record signature anywhere); `unsupported` for a ZIP VAT
+ *   will not take — no end record in the last 64 KiB, data before its first local header, ZIP64,
+ *   an end record or a directory two readers would read differently, one the ZIP reader cannot parse; `name-clash` for one
+ *   listing a name twice; `too-many-entries` or `too-large` for one past `limits`
+ */
+export declare function readZip(bytes: Buffer, archive: string, limits: ArchiveLimits): ArchiveRecord[];
+/**
+ * The ZIP of a directory tree VAT built, in memory: every file under `sourceDir`, named relative
+ * to it, each entry made on Unix with a directory `0755` and a file `0644`, or `0755` when the host
+ * marks it executable ({@link bytesMadeOnUnix}).
+ *
+ * @param sourceDir - The directory to archive
+ * @returns The archive's bytes
+ * @throws the raw errno of a listing or a read the OS refuses, for the caller to classify
+ */
+export declare function zipOfDirectory(sourceDir: string): Buffer;
+/** One entry of a ZIP VAT writes from entries it judged: a directory has no `data`. */
+interface WrittenZipEntry {
+    /** Where the entry lands: its segments joined with `/`, no empty, `.` or `..` segment. */
+    readonly place: string;
+    readonly data: Buffer | undefined;
+    readonly executable: boolean;
+}
+/**
+ * The ZIP of `entries`, in order, in memory — each a directory or a file with mode `0755` or
+ * `0644` by its executable bit, made on Unix on every host ({@link bytesMadeOnUnix}), nothing else
+ * of what an archive it came from said.
+ *
+ * @param entries - The entries, each named by the place it was judged at
+ * @returns The archive's bytes
+ */
+export declare function zipOfEntries(entries: readonly WrittenZipEntry[]): Buffer;
+export {};
+//# sourceMappingURL=zip-reader.d.ts.map

package/dist/archive/zip-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip-reader.d.ts","sourceRoot":"","sources":["../../src/archive/zip-reader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAyB,KAAK,aAAa,EAAoC,MAAM,cAAc,CAAC;AAE3G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAqIlD;;;GAGG;AACH,UAAU,aAAa;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,6GAA6G;AAC7G,QAAA,MAAM,aAAa,yDAA0D,CAAC;AAqG9E;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,SAAS,aAAa,EAAE,EACjC,OAAO,EAAE,aAAa,CAAC;IAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;CAAE,CAAC,GACnI,IAAI,CAMN;AAsBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,aAAa,EAAE,CAuB9F;AAkCD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,uFAAuF;AACvF,UAAU,eAAe;IACvB,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,GAAG,MAAM,CAQxE"}

package/dist/archive/zip-reader.js

@@ -0,0 +1,376 @@
+/**
+ * The ZIP reader and writer: every entry of a ZIP's central directory, each inflated only when
+ * asked, and the one ZIP VAT writes. One of the two files in VAT that import an archive library.
+ */
+import AdmZip from 'adm-zip';
+import { decodeTextContent } from '../text-content.js';
+import { ArchiveRefusedError, entryNameOf } from './entries.js';
+import { assertWithinLimits, tooManyEntries, unreadableArchive } from './limits.js';
+/** The host a ZIP entry was made on, in the high byte of `version made by`; 3 is Unix. */
+const MADE_ON_UNIX = 3;
+/** The file-type bits of a Unix mode, and the types among them. */
+const TYPE_MASK = 0o170000;
+const TYPE_REGULAR = 0o100000;
+const TYPE_DIRECTORY = 0o040000;
+const TYPE_LINK = 0o120000;
+/** Any of the owner, group or other execute bits. */
+const EXECUTE_BITS = 0o111;
+/** The permission bits a ZIP VAT writes gives a directory, an executable file and any other file. */
+const DIRECTORY_MODE = 0o755;
+const EXECUTABLE_MODE = 0o755;
+const FILE_MODE = 0o644;
+/** The Unix mode an entry made on Unix carries in its external attributes; `undefined` for any other host. */
+function unixModeOf(entry) {
+    return entry.header.made >>> 8 === MADE_ON_UNIX ? entry.attr >>> 16 : undefined;
+}
+function kindOf(entry, mode) {
+    const type = (mode ?? 0) & TYPE_MASK;
+    if (type === TYPE_LINK)
+        return 'link';
+    if (entry.isDirectory || type === TYPE_DIRECTORY)
+        return 'directory';
+    // No type bits: a ZIP made where there are none, or by a writer that set only permissions.
+    return type === 0 || type === TYPE_REGULAR ? 'file' : 'other';
+}
+function recordOf(entry) {
+    const mode = unixModeOf(entry);
+    const kind = kindOf(entry, mode);
+    return {
+        name: entryNameOf(entry.entryName),
+        kind,
+        size: kind === 'file' ? entry.header.size : 0,
+        executable: ((mode ?? 0) & EXECUTE_BITS) !== 0,
+        read: () => entry.getData(),
+    };
+}
+/** The end-of-central-directory record and one central-directory record: their signatures and fixed sizes. */
+const END_SIGNATURE = 0x06054b50;
+const END_SIZE = 22;
+const CENTRAL_SIGNATURE = 0x02014b50;
+const CENTRAL_SIZE = 46;
+/** A local file header's fixed size, before its name. */
+const LOCAL_HEADER_SIZE = 30;
+/** The longest comment that may follow the end record, so how far back from the end it can start. */
+const MAX_COMMENT = 0xffff;
+/** The 16-bit entry count a ZIP64 archive writes in place of its real one. */
+const COUNT_IN_ZIP64 = 0xffff;
+/** The ZIP64 end-of-central-directory locator and record: their signatures, and how far before the end record the ZIP library looks for either. */
+const ZIP64_LOCATOR_SIGNATURE = 0x07064b50;
+const ZIP64_RECORD_SIGNATURE = 0x06064b50;
+const ZIP64_LOCATOR_SIZE = 20;
+const NO_ZIP64 = 'which VAT does not read: no skill or plugin archive needs one';
+/**
+ * The refusal of a ZIP VAT found the end of and will not take — `unsupported`, never `unreadable`:
+ * `unreadable` is kept for bytes that are no ZIP at all, the one thing a lane may choose to pass
+ * on to a service that is the authority on them. This is a ZIP, and VAT's answer to it is no.
+ */
+function unsupportedZip(archive, why, cause) {
+    return new ArchiveRefusedError(archive, { reason: 'unsupported', why }, { cause });
+}
+/** The two signatures that make bytes a ZIP, as bytes to search for anywhere in them: a local file header's, and the end record's. */
+const LOCAL_SIGNATURE_BYTES = Buffer.from([0x50, 0x4b, 0x03, 0x04]);
+const END_SIGNATURE_BYTES = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+/**
+ * Whether `bytes` carry a ZIP signature at all: a local file header or an end record, ANYWHERE.
+ * Bytes with neither are no ZIP (`unreadable`); bytes with either and no end record a reader finds
+ * where every reader looks are a ZIP VAT will not take — one padded past that window, cut short,
+ * or behind other bytes, which a reader that searches further back, or scans forward for a local
+ * header, still takes.
+ */
+function holdsZipSignature(bytes) {
+    return bytes.includes(LOCAL_SIGNATURE_BYTES) || bytes.includes(END_SIGNATURE_BYTES);
+}
+/** Where the last end-of-central-directory record starts, searching back from the end as every reader does; `undefined` when there is none. */
+function endRecordAt(bytes) {
+    const last = bytes.length - END_SIZE;
+    for (let at = last; at >= Math.max(0, last - MAX_COMMENT); at--) {
+        if (bytes.readUInt32LE(at) === END_SIGNATURE)
+            return at;
+    }
+    return undefined;
+}
+/** Why a signature at `at` is refused, or `undefined` for bytes that are none of the three a reader looks for. */
+function signatureRefusal(bytes, at) {
+    const signature = bytes.readUInt32LE(at);
+    if (signature === ZIP64_LOCATOR_SIGNATURE || signature === ZIP64_RECORD_SIGNATURE)
+        return `it is a ZIP64 archive (a ZIP64 end-of-central-directory record or locator stands beside its end record), ${NO_ZIP64}`;
+    return signature === END_SIGNATURE ? 'it holds more than one end-of-central-directory record where two readers would choose differently' : undefined;
+}
+/**
+ * Refuse a ZIP whose end record a second reader could find differently — the first of the two
+ * locks on "which directory is this archive's" (the second is {@link sameDirectory}).
+ *
+ * The ZIP library scans back from 22 bytes before the end of the bytes and takes the FIRST
+ * signature it knows: an end record, or a ZIP64 record — which it meets first when one stands in
+ * the archive comment — and having found an end record it looks on through the 20 bytes before it
+ * for a ZIP64 locator or another end record. VAT's own reading is of the last end record. So the
+ * bytes around that record must hold nothing a scan could mistake for one:
+ *
+ * - the record is the END of the archive: it, and exactly the comment it declares, and nothing after;
+ * - no end-record, ZIP64-record or ZIP64-locator signature anywhere after the record's own
+ *   first byte (its fields, its comment) nor in the 20 bytes before it;
+ * - the central directory it names ends exactly where it starts.
+ *
+ * No archive within this module's limits needs ZIP64, so its frame is refused outright.
+ *
+ * @throws ArchiveRefusedError `unsupported`
+ */
+function refuseAmbiguousEndRecord(bytes, archive, end) {
+    if (end + END_SIZE + bytes.readUInt16LE(end + 20) !== bytes.length) {
+        throw unsupportedZip(archive, 'its end-of-central-directory record is not the end of the archive: the comment it declares and the bytes that follow it disagree');
+    }
+    for (let at = Math.max(0, end - ZIP64_LOCATOR_SIZE); at <= bytes.length - 4; at++) {
+        const refusal = at === end ? undefined : signatureRefusal(bytes, at);
+        if (refusal !== undefined)
+            throw unsupportedZip(archive, refusal);
+    }
+    if (bytes.readUInt32LE(end + 16) + bytes.readUInt32LE(end + 12) !== end) {
+        throw unsupportedZip(archive, 'its central directory does not end where its end-of-central-directory record begins');
+    }
+}
+/** The fields of a {@link CentralRecord} beside its name, as the ZIP library's entry header carries them. */
+const EXTENT_FIELDS = ['offset', 'compressedSize', 'size', 'method'];
+/**
+ * The records the central directory lists, read off the bytes — before the ZIP library builds
+ * a record for each, and whether or not it would accept them: the count is held to `limits`
+ * here, and a name listed twice is found here, by VAT's own reading and not the library's prose.
+ * `undefined` for bytes with no end record where a reader looks for one, for {@link readZip} to judge.
+ *
+ * The count read is the one the library loops over ("entries on this disk"); an end record whose
+ * two counts differ, or that defers them to ZIP64 fields, is refused, and so is a directory whose
+ * records do not run exactly from its start to the end record — so what is bounded and compared
+ * here is exactly what the library goes on to build ({@link refuseAmbiguousEndRecord}).
+ *
+ * @returns Each record, its name as the bytes the directory holds, in directory order; and where the directory starts
+ * @throws ArchiveRefusedError `too-many-entries`; `unsupported` for a ZIP64 archive, or an end
+ *   record or directory two readers would read differently
+ */
+function directoryRecords(bytes, archive, limits) {
+    const end = endRecordAt(bytes);
+    if (end === undefined)
+        return undefined;
+    refuseAmbiguousEndRecord(bytes, archive, end);
+    const count = bytes.readUInt16LE(end + 8);
+    if (count !== bytes.readUInt16LE(end + 10))
+        throw unsupportedZip(archive, 'its end-of-central-directory record counts its entries two ways (on this disk, and in total)');
+    if (count === COUNT_IN_ZIP64)
+        throw unsupportedZip(archive, `it is a ZIP64 archive (its end record defers the entry count to ZIP64 fields), ${NO_ZIP64}`);
+    if (count > limits.maxEntries)
+        throw tooManyEntries(archive, limits);
+    const records = [];
+    let at = bytes.readUInt32LE(end + 16);
+    for (let index = 0; index < count; index++) {
+        if (at + CENTRAL_SIZE > end || bytes.readUInt32LE(at) !== CENTRAL_SIGNATURE)
+            throw unsupportedZip(archive, `its central directory holds no record where its entry ${index + 1} of ${count} should be`);
+        const nameEnd = at + CENTRAL_SIZE + bytes.readUInt16LE(at + 28);
+        records.push({
+            name: bytes.subarray(at + CENTRAL_SIZE, nameEnd),
+            method: bytes.readUInt16LE(at + 10),
+            compressedSize: bytes.readUInt32LE(at + 20),
+            size: bytes.readUInt32LE(at + 24),
+            offset: bytes.readUInt32LE(at + 42),
+        });
+        at = nameEnd + bytes.readUInt16LE(at + 30) + bytes.readUInt16LE(at + 32);
+    }
+    if (at !== end)
+        throw unsupportedZip(archive, `its central directory holds more than the ${count} entries its end record counts`);
+    return { records, directoryAt: bytes.readUInt32LE(end + 16) };
+}
+/**
+ * Refuse a ZIP whose first byte is not the first local header its directory names (or, holding
+ * no entries, its directory): a self-extracting stub, or any other bytes put before the archive —
+ * whether or not its offsets were moved to step over them (`zip -A`): a ZIP no writer VAT takes
+ * from makes. ({@link refuseRecordWithoutItsLocalHeader} makes "the first local header its
+ * directory names" a header that is really there.)
+ *
+ * This closes unlisted bytes at the FRONT only: an unlisted local entry between listed ones, or
+ * after the last, is not refused. It is no defence on its own and need not be — no lane forwards
+ * an operator's ZIP bytes: every lane reads entries by the directory, and `zipOfArchive` re-writes
+ * only the entries it judged, so no unlisted entry leaves VAT.
+ *
+ * @throws ArchiveRefusedError `unsupported`
+ */
+function refuseDataBeforeFirstEntry(archive, { records, directoryAt }) {
+    const first = records.reduce((lowest, record) => Math.min(lowest, record.offset), directoryAt);
+    if (first !== 0)
+        throw unsupportedZip(archive, `it holds ${first} bytes before its first local file header (a self-extracting stub, or other data put before the archive), which a reader that reads local headers from the front would read`);
+}
+/** What a central record holds in a size or offset it defers to a ZIP64 extra field. */
+const DEFERRED_TO_ZIP64 = 0xff_ff_ff_ff;
+/**
+ * Refuse a ZIP one of whose central records holds {@link DEFERRED_TO_ZIP64} for a size or its
+ * offset. With a ZIP64 extra field the ZIP library reads another value than VAT and
+ * {@link sameDirectory} refuses it; with none both read `0xFFFFFFFF` and agree — and a directory,
+ * whose sizes are never used and whose data is never read, would pass. ZIP64 is refused outright.
+ *
+ * @throws ArchiveRefusedError `unsupported` (the archive as a whole; its message names the record)
+ */
+function refuseZip64Fields(archive, records) {
+    const deferred = records.find((record) => [record.compressedSize, record.size, record.offset].includes(DEFERRED_TO_ZIP64));
+    if (deferred !== undefined)
+        throw unsupportedZip(archive, `it is a ZIP64 archive (the central record of \`${decodeTextContent(deferred.name).text}\` holds 0xFFFFFFFF for a size or its offset), ${NO_ZIP64}`);
+}
+/** Whether a local file header for `record` — its signature, then its own name — starts at the offset the record names, before the directory. */
+function holdsItsLocalHeader(bytes, record, directoryAt) {
+    const { offset, name } = record;
+    if (offset + LOCAL_HEADER_SIZE > directoryAt || !bytes.subarray(offset, offset + LOCAL_SIGNATURE_BYTES.length).equals(LOCAL_SIGNATURE_BYTES))
+        return false;
+    const nameAt = offset + LOCAL_HEADER_SIZE;
+    return nameAt + name.length <= directoryAt && bytes.readUInt16LE(offset + 26) === name.length && bytes.subarray(nameAt, nameAt + name.length).equals(name);
+}
+/**
+ * Refuse a ZIP one of whose central records names an offset that does not hold that entry's own
+ * local header. The ZIP library reads a local header only when it inflates a file — never for a
+ * directory — so without this a directory record "at byte 0" stands over whatever is there, and
+ * the directory would be one two readers read differently. Like {@link refuseDataBeforeFirstEntry}
+ * it refuses only what a record points at: no lane forwards the operator's bytes, so an unlisted
+ * entry elsewhere is dropped by the re-zip, not refused here.
+ *
+ * @throws ArchiveRefusedError `unsupported` (the archive as a whole; its message names the record)
+ */
+function refuseRecordWithoutItsLocalHeader(bytes, archive, { records, directoryAt }) {
+    const headerless = records.find((record) => !holdsItsLocalHeader(bytes, record, directoryAt));
+    if (headerless !== undefined)
+        throw unsupportedZip(archive, `its central directory says the local file header of \`${decodeTextContent(headerless.name).text}\` is at byte ${headerless.offset}, and that entry's local header does not start there`);
+}
+/**
+ * The second lock on "which directory is this archive's": the ZIP library's OWN answer, held to
+ * VAT's. Whatever the two scans do, the entries the library built must be the entries VAT read
+ * off the bytes — the same count, the same names in the same order, and each extracted by the
+ * same local-header offset, sizes and method — or the archive is refused. A differential neither
+ * reading anticipated lands here instead of in an install: so does a per-entry ZIP64 extra field,
+ * which the library reads a size or an offset from wherever the central record holds 0xFFFFFFFF.
+ *
+ * @throws ArchiveRefusedError `unsupported`
+ */
+export function sameDirectory(archive, records, entries) {
+    const agree = entries.length === records.length && entries.every((entry, index) => {
+        const record = records[index];
+        return record?.name.equals(entry.rawEntryName) === true && EXTENT_FIELDS.every((field) => entry.header[field] === record[field]);
+    });
+    if (!agree)
+        throw unsupportedZip(archive, 'its central directory reads two ways: the entries the ZIP reader built are not the ones its end record names');
+}
+/**
+
+ * Refuse a ZIP whose directory lists one name twice: the archive's own clash — two readers resolve
+ * the name to different bytes — and the same `name-clash` a tarball listing a name twice is.
+ *
+ * @throws ArchiveRefusedError `name-clash`, naming the entry
+ */
+function refuseNameListedTwice(archive, records) {
+    const seen = new Set();
+    for (const { name: raw } of records) {
+        // Compared byte for byte: two names that only DECODE alike are two names.
+        const key = raw.toString('hex');
+        if (seen.has(key)) {
+            const name = decodeTextContent(raw).text;
+            throw new ArchiveRefusedError(archive, { reason: 'name-clash', entry: name, why: `it lists \`${name}\` twice` });
+        }
+        seen.add(key);
+    }
+}
+/**
+ * Every entry of the ZIP archive `bytes`, in central-directory order, each as the archive spells
+ * it — links, devices and unsafe names included: listing judges nothing. Nothing is inflated
+ * until a record is read, and the reader caps each inflation at the size the entry declares.
+ *
+ * @param bytes - The archive
+ * @param archive - What the operator named, for a refusal's message
+ * @param limits - The bounds the archive is held to, by what its entries declare
+ * @throws ArchiveRefusedError `unreadable` for bytes that are no ZIP archive at all (they hold
+ *   neither a local-file-header nor an end-record signature anywhere); `unsupported` for a ZIP VAT
+ *   will not take — no end record in the last 64 KiB, data before its first local header, ZIP64,
+ *   an end record or a directory two readers would read differently, one the ZIP reader cannot parse; `name-clash` for one
+ *   listing a name twice; `too-many-entries` or `too-large` for one past `limits`
+ */
+export function readZip(bytes, archive, limits) {
+    const directory = bytes.length < END_SIZE ? undefined : directoryRecords(bytes, archive, limits);
+    if (directory === undefined) {
+        if (holdsZipSignature(bytes))
+            throw unsupportedZip(archive, 'it carries a ZIP signature and no end-of-central-directory record where every reader looks for one (in its last 64 KiB): it is padded, cut short, or buried under other bytes, and a reader that looks elsewhere would read it');
+        throw unreadableArchive(archive, 'it is not a ZIP archive (its bytes hold neither a local file header nor an end-of-central-directory record)');
+    }
+    const { records } = directory;
+    refuseNameListedTwice(archive, records);
+    let entries;
+    try {
+        // The central directory is parsed at the first read of the entries, not when the archive is opened.
+        entries = new AdmZip(bytes).getEntries();
+    }
+    catch (error) {
+        throw unsupportedZip(archive, `the ZIP reader cannot read it (${String(error)})`, error);
+    }
+    sameDirectory(archive, records, entries);
+    refuseZip64Fields(archive, records);
+    // After the library's offsets are held to VAT's: an offset deferred to ZIP64 is that refusal, not this one.
+    refuseDataBeforeFirstEntry(archive, directory);
+    refuseRecordWithoutItsLocalHeader(bytes, archive, directory);
+    const listed = entries.map((entry) => recordOf(entry));
+    assertWithinLimits(archive, listed, limits);
+    return listed;
+}
+/** `version made by` in every entry VAT writes: host 3 (Unix), spec version 2.0. */
+const VERSION_MADE_ON_UNIX = (MADE_ON_UNIX << 8) | 20;
+/** The MS-DOS directory flag, in the low byte of an entry's external attributes. */
+const DOS_DIRECTORY = 0x10;
+/**
+ * The one mode policy of a ZIP VAT writes: a directory `0755`, a file `0755` when it is executable
+ * and `0644` otherwise — never a mode the host's `stat` made up.
+ *
+ * @returns The entry's external attributes: the Unix type and permission bits high, the DOS directory flag low
+ */
+function writtenAttributesOf(directory, executable) {
+    if (directory)
+        return (((TYPE_DIRECTORY | DIRECTORY_MODE) << 16) | DOS_DIRECTORY) >>> 0;
+    return ((TYPE_REGULAR | (executable ? EXECUTABLE_MODE : FILE_MODE)) << 16) >>> 0;
+}
+/**
+ * The bytes of `zip`, every entry made on Unix and holding the mode {@link writtenAttributesOf}
+ * gives it. The ZIP library stamps the host it RUNS on (NTFS on Windows) and copies whatever mode
+ * `stat` reports — on Windows a directory `0o40666`, a file `0o100666`, never an execute bit. A
+ * host-aware reader (VAT's own {@link unixModeOf}, Info-ZIP) applies the Unix mode only under host
+ * 3, so both are fixed here together: one archive is the same bytes wherever VAT writes it, and no
+ * directory in it is one a Unix reader cannot enter.
+ */
+function bytesMadeOnUnix(zip) {
+    for (const entry of zip.getEntries()) {
+        entry.header.made = VERSION_MADE_ON_UNIX;
+        entry.attr = writtenAttributesOf(entry.isDirectory, ((entry.attr >>> 16) & EXECUTE_BITS) !== 0);
+    }
+    return zip.toBuffer();
+}
+/**
+ * The ZIP of a directory tree VAT built, in memory: every file under `sourceDir`, named relative
+ * to it, each entry made on Unix with a directory `0755` and a file `0644`, or `0755` when the host
+ * marks it executable ({@link bytesMadeOnUnix}).
+ *
+ * @param sourceDir - The directory to archive
+ * @returns The archive's bytes
+ * @throws the raw errno of a listing or a read the OS refuses, for the caller to classify
+ */
+export function zipOfDirectory(sourceDir) {
+    const zip = new AdmZip();
+    zip.addLocalFolder(sourceDir);
+    return bytesMadeOnUnix(zip);
+}
+/**
+ * The ZIP of `entries`, in order, in memory — each a directory or a file with mode `0755` or
+ * `0644` by its executable bit, made on Unix on every host ({@link bytesMadeOnUnix}), nothing else
+ * of what an archive it came from said.
+ *
+ * @param entries - The entries, each named by the place it was judged at
+ * @returns The archive's bytes
+ */
+export function zipOfEntries(entries) {
+    const zip = new AdmZip();
+    for (const { place, data, executable } of entries) {
+        // Only the execute bit is read from what is added here; the mode itself is {@link bytesMadeOnUnix}'s.
+        if (data === undefined)
+            zip.addFile(`${place}/`, Buffer.alloc(0), '', DIRECTORY_MODE);
+        else
+            zip.addFile(place, data, '', executable ? EXECUTABLE_MODE : FILE_MODE);
+    }
+    return bytesMadeOnUnix(zip);
+}
+//# sourceMappingURL=zip-reader.js.map