@stigmer/zip-structure 3.13.0

package/src/zip-structure.ts

@@ -0,0 +1,248 @@
+/**
+ * Policy-free structural ZIP parsing: end-of-central-directory (EOCD)
+ * location plus central-directory walk, producing one record per entry.
+ *
+ * Lived in the runner (src/shared/zip-structure.ts) until the TS server's
+ * skill push gate became its second consumer; extracted to backend/libs/ts/
+ * per the program's shared-library rule (a library moves here when a second
+ * consumer exists — @stigmer/temporal-codecs is the precedent).
+ *
+ * Parsing is *central-directory-based* — never a front-to-back walk of
+ * local file headers. This is a correctness decision, not a style choice
+ * (issues #450 and #567): local headers of streaming entries
+ * (general-purpose flag bit 3) carry zeroed sizes, and the only
+ * local-only way to recover them is scanning the payload for the
+ * data-descriptor signature — which silently truncates any stored entry
+ * whose *content* happens to contain those four bytes, and
+ * desynchronizes every entry after it. The central directory always
+ * carries the real sizes, and every consumer here holds the complete
+ * archive bytes, so nothing a local-header walk could offer is needed.
+ *
+ * This layer maps bytes to entry records and nothing else. Policy — what
+ * a structural failure means, which entries are acceptable, how payloads
+ * are decoded — belongs to the consumers, and they differ on purpose:
+ *
+ *   - runner shared/zip-extract.ts (skill artifacts): structural failure
+ *     is NON-FATAL — both editions' push gates validated every artifact
+ *     with a central-directory-based reader before storage, so a defect
+ *     here can only be a truncated or corrupted download.
+ *   - runner execute-deep-agent/attachment-injector.ts (user
+ *     attachments): structural failure is FAIL-HARD — the input is an
+ *     untrusted upload and nothing upstream vouched for it.
+ *   - stigmer-server src/domain/skill/storage/ (the push gate):
+ *     FAIL-HARD, plus a safearchive-parity entry pre-filter decoded from
+ *     the raw creator/attribute fields exposed below.
+ *
+ * ZIP64 is deliberately unsupported: every consumer caps input far below
+ * every ZIP64 threshold (skill push gates: 100MB / 10,000 files;
+ * attachment uploads: 10MB).
+ *
+ * Throws plain `Error`s on structural defects (no valid EOCD, a central
+ * directory or local header record that does not parse, a payload slice
+ * that runs past the end of the buffer); consumers translate those into
+ * their own error models.
+ */
+
+// ─── Entry records ───────────────────────────────────────────────────────
+
+export interface ZipStructuralEntry {
+  /** Entry path exactly as recorded in the central directory. */
+  readonly name: string;
+  readonly isDirectory: boolean;
+  readonly compressionMethod: number;
+  /**
+   * The central directory's declared uncompressed size — authoritative for
+   * pre-extraction accounting (e.g. ZIP-bomb budgeting), but still a
+   * *declaration*: a consumer that distrusts its input must enforce it
+   * against the actual decompressed output.
+   */
+  readonly uncompressedSize: number;
+  /** The central directory's declared compressed size (the payload length). */
+  readonly compressedSize: number;
+  /**
+   * The central directory's CRC-32 of the uncompressed content, verbatim.
+   * Raw fact for consumers that verify payload integrity after
+   * decompression (Go's archive/zip checks it on every read); consumers
+   * that trust their input ignore it.
+   */
+  readonly crc32: number;
+  /**
+   * The central directory's "version made by" field, verbatim. The high
+   * byte identifies the creator OS (0 = MS-DOS/FAT, 3 = Unix, 19 = macOS),
+   * which decides how `externalAttributes` is interpreted. Raw facts for
+   * policy layers that decode entry file modes; most consumers ignore it.
+   */
+  readonly versionMadeBy: number;
+  /**
+   * The central directory's external file attributes field, verbatim.
+   * Unix creators store the POSIX mode in the high 16 bits; MS-DOS
+   * creators store FAT attribute bits in the low byte. Interpretation is
+   * policy — see the server's safearchive-parity pre-filter.
+   */
+  readonly externalAttributes: number;
+  /** The entry's raw payload slice (a view, not a copy) of the archive buffer. */
+  readonly compressedData: Uint8Array;
+}
+
+// ─── Format constants ────────────────────────────────────────────────────
+
+const LOCAL_FILE_HEADER_SIG = 0x04034b50;
+const CENTRAL_DIRECTORY_SIG = 0x02014b50;
+const EOCD_SIG = 0x06054b50;
+
+/** Fixed size of the EOCD record, excluding the variable-length comment. */
+export const EOCD_MIN_SIZE = 22;
+/** The archive comment length is a u16, so the EOCD sits within the last 64KB + 22 bytes. */
+const EOCD_MAX_COMMENT = 0xffff;
+
+const LOCAL_HEADER_SIZE = 30;
+const CD_RECORD_SIZE = 46;
+
+// ─── Parsing ─────────────────────────────────────────────────────────────
+
+/**
+ * Enumerate the archive's entries from its central directory.
+ *
+ * Throws on any structural defect: no valid EOCD, a central directory or
+ * local header record that doesn't parse, or a payload slice that runs
+ * past the end of the buffer.
+ */
+export function parseZipStructure(data: Uint8Array): ZipStructuralEntry[] {
+  const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
+  const eocd = findEndOfCentralDirectory(data, view);
+
+  const entries: ZipStructuralEntry[] = [];
+  let offset = eocd.centralDirectoryOffset;
+
+  for (let i = 0; i < eocd.entryCount; i++) {
+    if (offset + CD_RECORD_SIZE > data.length || view.getUint32(offset, true) !== CENTRAL_DIRECTORY_SIG) {
+      throw new Error(`invalid central directory record at offset ${offset}`);
+    }
+
+    const versionMadeBy = view.getUint16(offset + 4, true);
+    const compressionMethod = view.getUint16(offset + 10, true);
+    const crc32 = view.getUint32(offset + 16, true);
+    const compressedSize = view.getUint32(offset + 20, true);
+    const uncompressedSize = view.getUint32(offset + 24, true);
+    const fileNameLength = view.getUint16(offset + 28, true);
+    const extraFieldLength = view.getUint16(offset + 30, true);
+    const commentLength = view.getUint16(offset + 32, true);
+    const externalAttributes = view.getUint32(offset + 38, true);
+    const localHeaderOffset = view.getUint32(offset + 42, true);
+
+    const fileName = new TextDecoder().decode(
+      data.subarray(offset + CD_RECORD_SIZE, offset + CD_RECORD_SIZE + fileNameLength),
+    );
+
+    // The local header is consulted for one thing only: the payload start.
+    // Its name/extra field lengths can legitimately differ from the central
+    // directory's (streaming writers pad the extra field), so the offset
+    // cannot be derived from CD fields alone.
+    const dataStart = payloadStart(data, view, localHeaderOffset, fileName);
+    if (dataStart + compressedSize > data.length) {
+      throw new Error(`entry "${fileName}" payload runs past end of archive`);
+    }
+
+    entries.push({
+      name: fileName,
+      isDirectory: fileName.endsWith("/"),
+      compressionMethod,
+      uncompressedSize,
+      compressedSize,
+      crc32,
+      versionMadeBy,
+      externalAttributes,
+      compressedData: data.subarray(dataStart, dataStart + compressedSize),
+    });
+
+    offset += CD_RECORD_SIZE + fileNameLength + extraFieldLength + commentLength;
+  }
+
+  return entries;
+}
+
+interface EndOfCentralDirectory {
+  centralDirectoryOffset: number;
+  entryCount: number;
+}
+
+/**
+ * Locate and validate the end-of-central-directory record.
+ *
+ * Scans backward from the end of the archive across the maximum comment
+ * span. A signature match alone is not trusted (the four bytes can occur
+ * inside a trailing comment): the record must also point at an offset
+ * that actually holds a central directory record, or be a genuinely
+ * empty archive.
+ */
+function findEndOfCentralDirectory(data: Uint8Array, view: DataView): EndOfCentralDirectory {
+  const scanFloor = Math.max(0, data.length - EOCD_MIN_SIZE - EOCD_MAX_COMMENT);
+
+  for (let pos = data.length - EOCD_MIN_SIZE; pos >= scanFloor; pos--) {
+    if (view.getUint32(pos, true) !== EOCD_SIG) continue;
+
+    const entryCount = view.getUint16(pos + 10, true);
+    const centralDirectorySize = view.getUint32(pos + 12, true);
+    const centralDirectoryOffset = view.getUint32(pos + 16, true);
+
+    const directoryEndsAtRecord = centralDirectoryOffset + centralDirectorySize <= pos;
+    const directoryLooksReal =
+      entryCount === 0 ||
+      (centralDirectoryOffset + 4 <= data.length &&
+        view.getUint32(centralDirectoryOffset, true) === CENTRAL_DIRECTORY_SIG);
+
+    if (directoryEndsAtRecord && directoryLooksReal) {
+      return { centralDirectoryOffset, entryCount };
+    }
+  }
+
+  throw new Error("no end-of-central-directory record found");
+}
+
+// ─── CRC-32 ──────────────────────────────────────────────────────────────
+
+// Standard CRC-32 (IEEE 802.3, the ZIP checksum), table-driven so callers
+// hashing payloads at the consumers' 100 MB caps stay cheap.
+const CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let bit = 0; bit < 8; bit++) {
+      c = (c >>> 1) ^ (0xedb88320 & -(c & 1));
+    }
+    table[n] = c;
+  }
+  return table;
+})();
+
+/**
+ * CRC-32 of `data` — the ZIP checksum. Exported for consumers that verify
+ * decompressed payloads against an entry's declared `crc32` (Go's
+ * archive/zip does this on every read) and for the fixture builder.
+ */
+export function crc32(data: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (let i = 0; i < data.length; i++) {
+    crc = (crc >>> 8) ^ CRC_TABLE[(crc ^ data[i]!) & 0xff]!;
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}
+
+/** Resolve where an entry's payload begins, from its local file header. */
+function payloadStart(
+  data: Uint8Array,
+  view: DataView,
+  localHeaderOffset: number,
+  fileName: string,
+): number {
+  if (
+    localHeaderOffset + LOCAL_HEADER_SIZE > data.length ||
+    view.getUint32(localHeaderOffset, true) !== LOCAL_FILE_HEADER_SIG
+  ) {
+    throw new Error(`entry "${fileName}" has no local file header at offset ${localHeaderOffset}`);
+  }
+
+  const localNameLength = view.getUint16(localHeaderOffset + 26, true);
+  const localExtraLength = view.getUint16(localHeaderOffset + 28, true);
+  return localHeaderOffset + LOCAL_HEADER_SIZE + localNameLength + localExtraLength;
+}

package/testing.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Byte-level ZIP fixture builder for the structural parser's consumers'
+ * tests (exported as `@stigmer/zip-structure/testing`). Moved here from the
+ * runner's src/__test-utils__/zip-fixtures.ts when the lib was extracted —
+ * the lib's own tests, the runner's, and the TS server's skill-gate tests
+ * all craft archives with it, and one builder keeps their fixture shapes
+ * from drifting apart.
+ *
+ * Emits complete, real-shaped archives — local file headers (optionally
+ * streaming-style, the Go stdlib writer's default), payloads, central
+ * directory, and EOCD — because that is the only shape that can reach the
+ * runner: both editions' skill push gates validate artifacts with
+ * central-directory-based readers (see zip-structure.ts's module doc).
+ * Earlier fixtures emitted local headers only, a shape no real ZIP writer
+ * produces, and were coupled to the old parser's front-to-back walk.
+ *
+ * Mirrors the conformance suite's `zipFilesStreaming()`
+ * (test/conformance/src/support/skills.ts) so unit fixtures and
+ * cross-edition fixtures share one shape.
+ */
+export interface ZipFixtureFile {
+    name: string;
+    /** Text content is UTF-8 encoded; pass bytes directly for binary payloads. */
+    content: string | Uint8Array;
+    /** Compression method for the entry. Defaults to stored. */
+    method?: "stored" | "deflated";
+    /**
+     * Emit the entry the way Go's archive/zip does by default: general-purpose
+     * flag bit 3 set, zeroed sizes in the local header, and a trailing data
+     * descriptor (with the conventional signature) carrying the real values.
+     */
+    streaming?: boolean;
+    /**
+     * Lie about the entry's uncompressed size everywhere the writer would
+     * declare it (local header, data descriptor, central directory). Models a
+     * crafted archive whose declarations disagree with its actual payload —
+     * the input class the attachment injector's declared-size enforcement
+     * exists to reject (issue #567).
+     */
+    declaredUncompressedSize?: number;
+    /**
+     * The central directory's "version made by" field. Defaults to 20
+     * (MS-DOS creator, the historical fixture value). Set the high byte to
+     * 3 (`0x0300 | 20`) to model a Unix creator, which makes readers
+     * interpret `externalAttributes`' high 16 bits as a POSIX mode — how
+     * symlink and device entries are represented (the server's
+     * safearchive-parity pre-filter fixtures need this).
+     */
+    versionMadeBy?: number;
+    /** The central directory's external file attributes field. Defaults to 0. */
+    externalAttributes?: number;
+}
+export interface ZipFixtureOptions {
+    /** Trailing archive comment appended after the EOCD record. */
+    comment?: string;
+    /**
+     * Drop the central directory and EOCD, leaving only local headers and
+     * payloads. No real ZIP writer produces this shape — it models a download
+     * truncated before the archive's index.
+     */
+    omitCentralDirectory?: boolean;
+}
+/** Build a ZIP archive from path + content pairs. */
+export declare function buildZip(files: ZipFixtureFile[], options?: ZipFixtureOptions): Uint8Array;
+//# sourceMappingURL=testing.d.ts.map

package/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAMH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,EAAE,MAAM,GAAG,UAAU,CAAC;IAC7B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAC;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,qDAAqD;AACrD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,cAAc,EAAE,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,CA+FzF"}

package/testing.js

@@ -0,0 +1,132 @@
+/**
+ * Byte-level ZIP fixture builder for the structural parser's consumers'
+ * tests (exported as `@stigmer/zip-structure/testing`). Moved here from the
+ * runner's src/__test-utils__/zip-fixtures.ts when the lib was extracted —
+ * the lib's own tests, the runner's, and the TS server's skill-gate tests
+ * all craft archives with it, and one builder keeps their fixture shapes
+ * from drifting apart.
+ *
+ * Emits complete, real-shaped archives — local file headers (optionally
+ * streaming-style, the Go stdlib writer's default), payloads, central
+ * directory, and EOCD — because that is the only shape that can reach the
+ * runner: both editions' skill push gates validate artifacts with
+ * central-directory-based readers (see zip-structure.ts's module doc).
+ * Earlier fixtures emitted local headers only, a shape no real ZIP writer
+ * produces, and were coupled to the old parser's front-to-back walk.
+ *
+ * Mirrors the conformance suite's `zipFilesStreaming()`
+ * (test/conformance/src/support/skills.ts) so unit fixtures and
+ * cross-edition fixtures share one shape.
+ */
+import { deflateRawSync } from "node:zlib";
+import { crc32 } from "./zip-structure.js";
+/** Build a ZIP archive from path + content pairs. */
+export function buildZip(files, options) {
+    const out = new ByteWriter();
+    const written = [];
+    for (const file of files) {
+        const contentBytes = typeof file.content === "string" ? new TextEncoder().encode(file.content) : file.content;
+        const deflated = file.method === "deflated";
+        const payload = deflated ? new Uint8Array(deflateRawSync(contentBytes)) : contentBytes;
+        const entry = {
+            nameBytes: new TextEncoder().encode(file.name),
+            payload,
+            declaredUncompressed: file.declaredUncompressedSize ?? contentBytes.length,
+            crc: crc32(contentBytes),
+            flags: file.streaming ? 0x0008 : 0,
+            method: deflated ? 8 : 0,
+            versionMadeBy: file.versionMadeBy ?? 20,
+            externalAttributes: file.externalAttributes ?? 0,
+            localHeaderOffset: out.length,
+        };
+        written.push(entry);
+        out.u32(0x04034b50); // local file header signature
+        out.u16(20); // version needed to extract
+        out.u16(entry.flags);
+        out.u16(entry.method);
+        out.u16(0); // mod time
+        out.u16(0); // mod date
+        out.u32(file.streaming ? 0 : entry.crc);
+        out.u32(file.streaming ? 0 : payload.length);
+        out.u32(file.streaming ? 0 : entry.declaredUncompressed);
+        out.u16(entry.nameBytes.length);
+        out.u16(0); // extra field length
+        out.raw(entry.nameBytes);
+        out.raw(payload);
+        if (file.streaming) {
+            out.u32(0x08074b50); // data descriptor signature (Go writes it)
+            out.u32(entry.crc);
+            out.u32(payload.length);
+            out.u32(entry.declaredUncompressed);
+        }
+    }
+    if (options?.omitCentralDirectory) {
+        return out.toUint8Array();
+    }
+    const centralDirectoryOffset = out.length;
+    for (const entry of written) {
+        out.u32(0x02014b50); // central directory record signature
+        out.u16(entry.versionMadeBy);
+        out.u16(20); // version needed to extract
+        out.u16(entry.flags);
+        out.u16(entry.method);
+        out.u16(0); // mod time
+        out.u16(0); // mod date
+        out.u32(entry.crc);
+        out.u32(entry.payload.length);
+        out.u32(entry.declaredUncompressed);
+        out.u16(entry.nameBytes.length);
+        out.u16(0); // extra field length
+        out.u16(0); // comment length
+        out.u16(0); // disk number start
+        out.u16(0); // internal attributes
+        out.u32(entry.externalAttributes);
+        out.u32(entry.localHeaderOffset);
+        out.raw(entry.nameBytes);
+    }
+    const centralDirectorySize = out.length - centralDirectoryOffset;
+    const commentBytes = new TextEncoder().encode(options?.comment ?? "");
+    out.u32(0x06054b50); // EOCD signature
+    out.u16(0); // disk number
+    out.u16(0); // disk with central directory
+    out.u16(written.length); // entries on this disk
+    out.u16(written.length); // total entries
+    out.u32(centralDirectorySize);
+    out.u32(centralDirectoryOffset);
+    out.u16(commentBytes.length);
+    out.raw(commentBytes);
+    return out.toUint8Array();
+}
+// Chunked assembly instead of a number[]-per-byte accumulator: fixtures at
+// the injector's 100 MB zip-bomb limit are built from payload-sized chunks,
+// which a per-byte spread-push cannot survive (argument-count overflow).
+class ByteWriter {
+    chunks = [];
+    size = 0;
+    get length() {
+        return this.size;
+    }
+    u16(v) {
+        this.raw(new Uint8Array([v & 0xff, (v >>> 8) & 0xff]));
+    }
+    u32(v) {
+        this.raw(new Uint8Array([v & 0xff, (v >>> 8) & 0xff, (v >>> 16) & 0xff, (v >>> 24) & 0xff]));
+    }
+    raw(b) {
+        this.chunks.push(b);
+        this.size += b.length;
+    }
+    toUint8Array() {
+        const result = new Uint8Array(this.size);
+        let offset = 0;
+        for (const chunk of this.chunks) {
+            result.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return result;
+    }
+}
+// CRC-32 comes from the structural module (one implementation for the
+// parser's consumers and this builder; semantically identical to the
+// conformance suite's inline bit-loop helper).
+//# sourceMappingURL=testing.js.map

package/testing.js.map

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

package/zip-structure.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Policy-free structural ZIP parsing: end-of-central-directory (EOCD)
+ * location plus central-directory walk, producing one record per entry.
+ *
+ * Lived in the runner (src/shared/zip-structure.ts) until the TS server's
+ * skill push gate became its second consumer; extracted to backend/libs/ts/
+ * per the program's shared-library rule (a library moves here when a second
+ * consumer exists — @stigmer/temporal-codecs is the precedent).
+ *
+ * Parsing is *central-directory-based* — never a front-to-back walk of
+ * local file headers. This is a correctness decision, not a style choice
+ * (issues #450 and #567): local headers of streaming entries
+ * (general-purpose flag bit 3) carry zeroed sizes, and the only
+ * local-only way to recover them is scanning the payload for the
+ * data-descriptor signature — which silently truncates any stored entry
+ * whose *content* happens to contain those four bytes, and
+ * desynchronizes every entry after it. The central directory always
+ * carries the real sizes, and every consumer here holds the complete
+ * archive bytes, so nothing a local-header walk could offer is needed.
+ *
+ * This layer maps bytes to entry records and nothing else. Policy — what
+ * a structural failure means, which entries are acceptable, how payloads
+ * are decoded — belongs to the consumers, and they differ on purpose:
+ *
+ *   - runner shared/zip-extract.ts (skill artifacts): structural failure
+ *     is NON-FATAL — both editions' push gates validated every artifact
+ *     with a central-directory-based reader before storage, so a defect
+ *     here can only be a truncated or corrupted download.
+ *   - runner execute-deep-agent/attachment-injector.ts (user
+ *     attachments): structural failure is FAIL-HARD — the input is an
+ *     untrusted upload and nothing upstream vouched for it.
+ *   - stigmer-server src/domain/skill/storage/ (the push gate):
+ *     FAIL-HARD, plus a safearchive-parity entry pre-filter decoded from
+ *     the raw creator/attribute fields exposed below.
+ *
+ * ZIP64 is deliberately unsupported: every consumer caps input far below
+ * every ZIP64 threshold (skill push gates: 100MB / 10,000 files;
+ * attachment uploads: 10MB).
+ *
+ * Throws plain `Error`s on structural defects (no valid EOCD, a central
+ * directory or local header record that does not parse, a payload slice
+ * that runs past the end of the buffer); consumers translate those into
+ * their own error models.
+ */
+export interface ZipStructuralEntry {
+    /** Entry path exactly as recorded in the central directory. */
+    readonly name: string;
+    readonly isDirectory: boolean;
+    readonly compressionMethod: number;
+    /**
+     * The central directory's declared uncompressed size — authoritative for
+     * pre-extraction accounting (e.g. ZIP-bomb budgeting), but still a
+     * *declaration*: a consumer that distrusts its input must enforce it
+     * against the actual decompressed output.
+     */
+    readonly uncompressedSize: number;
+    /** The central directory's declared compressed size (the payload length). */
+    readonly compressedSize: number;
+    /**
+     * The central directory's CRC-32 of the uncompressed content, verbatim.
+     * Raw fact for consumers that verify payload integrity after
+     * decompression (Go's archive/zip checks it on every read); consumers
+     * that trust their input ignore it.
+     */
+    readonly crc32: number;
+    /**
+     * The central directory's "version made by" field, verbatim. The high
+     * byte identifies the creator OS (0 = MS-DOS/FAT, 3 = Unix, 19 = macOS),
+     * which decides how `externalAttributes` is interpreted. Raw facts for
+     * policy layers that decode entry file modes; most consumers ignore it.
+     */
+    readonly versionMadeBy: number;
+    /**
+     * The central directory's external file attributes field, verbatim.
+     * Unix creators store the POSIX mode in the high 16 bits; MS-DOS
+     * creators store FAT attribute bits in the low byte. Interpretation is
+     * policy — see the server's safearchive-parity pre-filter.
+     */
+    readonly externalAttributes: number;
+    /** The entry's raw payload slice (a view, not a copy) of the archive buffer. */
+    readonly compressedData: Uint8Array;
+}
+/** Fixed size of the EOCD record, excluding the variable-length comment. */
+export declare const EOCD_MIN_SIZE = 22;
+/**
+ * Enumerate the archive's entries from its central directory.
+ *
+ * Throws on any structural defect: no valid EOCD, a central directory or
+ * local header record that doesn't parse, or a payload slice that runs
+ * past the end of the buffer.
+ */
+export declare function parseZipStructure(data: Uint8Array): ZipStructuralEntry[];
+/**
+ * CRC-32 of `data` — the ZIP checksum. Exported for consumers that verify
+ * decompressed payloads against an entry's declared `crc32` (Go's
+ * archive/zip does this on every read) and for the fixture builder.
+ */
+export declare function crc32(data: Uint8Array): number;
+//# sourceMappingURL=zip-structure.d.ts.map

package/zip-structure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip-structure.d.ts","sourceRoot":"","sources":["../src/zip-structure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AAIH,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,6EAA6E;IAC7E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,gFAAgF;IAChF,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC;CACrC;AAQD,4EAA4E;AAC5E,eAAO,MAAM,aAAa,KAAK,CAAC;AAShC;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,kBAAkB,EAAE,CAoDxE;AAwDD;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAM9C"}