@stigmer/runner 3.12.9 → 3.14.0-dev.20260910084630

package/dist/shared/zip-structure.js

@@ -1,128 +0,0 @@
-/**
- * Policy-free structural ZIP parsing: end-of-central-directory (EOCD)
- * location plus central-directory walk, producing one record per entry.
- *
- * 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:
- *
- *   - 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.
- *   - 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.
- *
- * ZIP64 is deliberately unsupported: both consumers cap 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.
- */
-// ─── 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) {
-    const view = new DataView(data.buffer, data.byteOffset, data.byteLength);
-    const eocd = findEndOfCentralDirectory(data, view);
-    const entries = [];
-    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 compressionMethod = view.getUint16(offset + 10, 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 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,
-            compressedData: data.subarray(dataStart, dataStart + compressedSize),
-        });
-        offset += CD_RECORD_SIZE + fileNameLength + extraFieldLength + commentLength;
-    }
-    return entries;
-}
-/**
- * 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, view) {
-    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");
-}
-/** Resolve where an entry's payload begins, from its local file header. */
-function payloadStart(data, view, localHeaderOffset, fileName) {
-    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;
-}
-//# sourceMappingURL=zip-structure.js.map

package/dist/shared/zip-structure.js.map

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

package/src/__test-utils__/zip-fixtures.ts

@@ -1,206 +0,0 @@
-/**
- * Shared ZIP fixture builder for runner unit tests.
- *
- * 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-extract.ts's module doc and
- * design record 017). 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.
- *
- * Lives in src/__test-utils__/ so `tsc --noEmit` covers it while
- * tsconfig.build.json keeps it out of dist/.
- */
-
-import { deflateRawSync } from "node:zlib";
-
-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;
-}
-
-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 function buildZip(files: ZipFixtureFile[], options?: ZipFixtureOptions): Uint8Array {
-  const out = new ByteWriter();
-
-  interface WrittenEntry {
-    nameBytes: Uint8Array;
-    payload: Uint8Array;
-    declaredUncompressed: number;
-    crc: number;
-    flags: number;
-    method: number;
-    localHeaderOffset: number;
-  }
-  const written: WrittenEntry[] = [];
-
-  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: WrittenEntry = {
-      nameBytes: new TextEncoder().encode(file.name),
-      payload,
-      declaredUncompressed: file.declaredUncompressedSize ?? contentBytes.length,
-      crc: crc32(contentBytes),
-      flags: file.streaming ? 0x0008 : 0,
-      method: deflated ? 8 : 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(20); // version made by
-    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(0); // external attributes
-    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 {
-  private readonly chunks: Uint8Array[] = [];
-  private size = 0;
-
-  get length(): number {
-    return this.size;
-  }
-
-  u16(v: number): void {
-    this.raw(new Uint8Array([v & 0xff, (v >>> 8) & 0xff]));
-  }
-
-  u32(v: number): void {
-    this.raw(new Uint8Array([v & 0xff, (v >>> 8) & 0xff, (v >>> 16) & 0xff, (v >>> 24) & 0xff]));
-  }
-
-  raw(b: Uint8Array): void {
-    this.chunks.push(b);
-    this.size += b.length;
-  }
-
-  toUint8Array(): Uint8Array {
-    const result = new Uint8Array(this.size);
-    let offset = 0;
-    for (const chunk of this.chunks) {
-      result.set(chunk, offset);
-      offset += chunk.length;
-    }
-    return result;
-  }
-}
-
-// Standard CRC-32 (IEEE 802.3, the ZIP checksum), table-driven so fixtures
-// at the injector's 100 MB limit stay cheap to build. Semantically identical
-// to the conformance suite's inline bit-loop helper.
-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;
-})();
-
-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;
-}

package/src/shared/zip-structure.ts

@@ -1,181 +0,0 @@
-/**
- * Policy-free structural ZIP parsing: end-of-central-directory (EOCD)
- * location plus central-directory walk, producing one record per entry.
- *
- * 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:
- *
- *   - 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.
- *   - 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.
- *
- * ZIP64 is deliberately unsupported: both consumers cap 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 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 compressionMethod = view.getUint16(offset + 10, 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 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,
-      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");
-}
-
-/** 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;
-}