@chestnutlabs/gcode-containers 0.1.0

package/README.md

@@ -0,0 +1,16 @@
+# @chestnutlabs/gcode-containers
+
+Safe, bounded, **zero-dependency container extraction** for sliced G-code archives —
+`.gcode.3mf` (sliced-plate export) and plain ZIP — for the Chestnut Labs G-code Preview stack
+(design: DD-005, security review DD-005 §7.3).
+
+- In-memory ZIP reader with strict resource limits (entry counts, sizes, name policies)
+- `.gcode.3mf` plate discovery and selection (multi-plate via the wire `plate` option)
+- Hardened against adversarial archives — a manifest-tracked adversarial corpus rides in CI, and
+  coverage-guided fuzzing over `readDirectory`/`streamEntry` is part of the release gate
+
+This package is bundled into the parser's default *batteries* worker — most applications never
+import it directly. Import it to build a custom worker or to consume containers outside the
+parse pipeline.
+
+Part of [Chestnut Labs G-code Preview](../../README.md) · MIT

package/dist/gcode-3mf.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `.gcode.3mf` container adapter (DD-005 §4.4, as amended) — the Bambu
+ * Studio / OrcaSlicer sliced-project ZIP: per-plate G-code payloads under
+ * `Metadata/plate_*.gcode` plus machine/filament configuration.
+ *
+ * Lifecycle (amendment 3): `open()` is DISCOVERY ONLY (central directory +
+ * bounded metadata — no payload inflate); the consumer selects a plate;
+ * `openPlate(i)` streams exactly one payload with incremental caps and
+ * end-of-stream CRC verification.
+ */
+import type { MachineGeometry, FilamentInfo } from '@chestnutlabs/toolpath-core';
+import { type ContainerLimits } from './zip.js';
+export interface PlateEntry {
+    index: number;
+    name: string;
+    estimatedBytes: number;
+}
+export interface ContainerMetadata {
+    machine?: MachineGeometry;
+    filaments?: FilamentInfo[];
+    /** Whitelisted key/value settings (bounded) — also feeds dialect detection. */
+    raw: Record<string, string>;
+    warnings: {
+        code: string;
+        message: string;
+    }[];
+}
+export interface StreamLike {
+    getReader(): {
+        read(): Promise<{
+            done: boolean;
+            value?: Uint8Array;
+        }>;
+        releaseLock?(): void;
+    };
+}
+export interface OpenedContainer {
+    id: 'gcode-3mf';
+    plates: PlateEntry[];
+    metadata: ContainerMetadata;
+    openPlate(index: number): StreamLike;
+}
+export declare function sniffGcode3mf(prefix: Uint8Array, name?: string): boolean;
+export declare function openGcode3mf(bytes: Uint8Array, limits?: ContainerLimits): Promise<OpenedContainer>;
+//# sourceMappingURL=gcode-3mf.d.ts.map

package/dist/gcode-3mf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gcode-3mf.d.ts","sourceRoot":"","sources":["../src/gcode-3mf.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAU,MAAM,6BAA6B,CAAC;AACzF,OAAO,EASL,KAAK,eAAe,EAErB,MAAM,UAAU,CAAC;AAElB,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B,SAAS,CAAC,EAAE,YAAY,EAAE,CAAC;IAC3B,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C;AAED,MAAM,WAAW,UAAU;IACzB,SAAS,IAAI;QAAE,IAAI,IAAI,OAAO,CAAC;YAAE,IAAI,EAAE,OAAO,CAAC;YAAC,KAAK,CAAC,EAAE,UAAU,CAAA;SAAE,CAAC,CAAC;QAAC,WAAW,CAAC,IAAI,IAAI,CAAA;KAAE,CAAC;CAC/F;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,WAAW,CAAC;IAChB,MAAM,EAAE,UAAU,EAAE,CAAC;IACrB,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;CACtC;AAgBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAKxE;AAqDD,wBAAsB,YAAY,CAChC,KAAK,EAAE,UAAU,EACjB,MAAM,GAAE,eAA0C,GACjD,OAAO,CAAC,eAAe,CAAC,CA2G1B"}

package/dist/gcode-3mf.js

@@ -0,0 +1,169 @@
+import { ContainerError, DEFAULT_CONTAINER_LIMITS, canonicalName, crc32, crc32Final, extractEntry, readDirectory, streamEntry } from './zip.js';
+const ZIP_MAGIC = [0x50, 0x4b, 0x03, 0x04];
+const PLATE_RE = /^metadata\/plate_(\d+)\.gcode$/;
+/** Settings keys copied into metadata.raw — a whitelist, never the whole config. */
+const RAW_WHITELIST = [
+    'printer_model',
+    'printer_settings_id',
+    'print_settings_id',
+    'printable_height',
+    'nozzle_diameter',
+    'filament_type',
+    'filament_colour',
+    'version'
+];
+export function sniffGcode3mf(prefix, name) {
+    const magic = prefix.length >= 4 && ZIP_MAGIC.every((b, i) => prefix[i] === b);
+    if (!magic)
+        return false;
+    // Extension hint refines but never overrides the magic (a .zip named .gcode is still not a container).
+    return name === undefined || /\.(gcode\.)?3mf$/i.test(name) || true;
+}
+/** Bambu/Orca `printable_area`: ["0x0","256x0","256x256","0x256"] or "0x0,256x0,..." */
+function parsePrintableArea(value) {
+    const parts = Array.isArray(value) ? value : typeof value === 'string' ? value.split(',') : null;
+    if (parts === null || parts.length < 3 || parts.length > 64)
+        return null;
+    const points = [];
+    for (const p of parts) {
+        if (typeof p !== 'string')
+            return null;
+        const m = /^\s*(-?\d+(?:\.\d+)?)x(-?\d+(?:\.\d+)?)\s*$/.exec(p);
+        if (m === null)
+            return null;
+        points.push({ x: parseFloat(m[1]), y: parseFloat(m[2]) });
+    }
+    return points;
+}
+function machineFromSettings(settings) {
+    const points = parsePrintableArea(settings['printable_area']);
+    if (points === null)
+        return undefined;
+    const xs = points.map((p) => p.x);
+    const ys = points.map((p) => p.y);
+    const min = { x: Math.min(...xs), y: Math.min(...ys) };
+    const max = { x: Math.max(...xs), y: Math.max(...ys) };
+    const axisAlignedRect = points.length === 4 && points.every((p) => (p.x === min.x || p.x === max.x) && (p.y === min.y || p.y === max.y));
+    const height = Number(settings['printable_height']);
+    const printerName = typeof settings['printer_model'] === 'string'
+        ? settings['printer_model']
+        : typeof settings['printer_settings_id'] === 'string'
+            ? settings['printer_settings_id']
+            : undefined;
+    return {
+        bed: axisAlignedRect ? { kind: 'rect', min, max } : { kind: 'polygon', points },
+        origin: { x: 0, y: 0 },
+        heightMm: Number.isFinite(height) ? height : undefined,
+        printerName,
+        confidence: 'known', // read from the project's own machine config
+        source: { adapterId: 'gcode-3mf', evidence: 'Metadata/project_settings.config printable_area' }
+    };
+}
+function filamentsFromSettings(settings) {
+    const types = settings['filament_type'];
+    if (!Array.isArray(types))
+        return undefined;
+    const colours = Array.isArray(settings['filament_colour']) ? settings['filament_colour'] : [];
+    return types.slice(0, 64).map((t, i) => ({
+        slot: i,
+        type: typeof t === 'string' ? t : undefined,
+        color: typeof colours[i] === 'string' ? colours[i] : undefined
+    }));
+}
+export async function openGcode3mf(bytes, limits = DEFAULT_CONTAINER_LIMITS) {
+    const dir = readDirectory(bytes, limits);
+    const warnings = [...dir.warnings];
+    const plates = [];
+    for (const entry of dir.entries) {
+        const m = PLATE_RE.exec(entry.name);
+        if (m !== null) {
+            plates.push({ index: plates.length, name: entry.rawName, estimatedBytes: entry.uncompressedSize, entry });
+        }
+    }
+    plates.sort((a, b) => parseInt(PLATE_RE.exec(a.name.toLowerCase())?.[1] ?? '0') -
+        parseInt(PLATE_RE.exec(b.name.toLowerCase())?.[1] ?? '0'));
+    plates.forEach((p, i) => (p.index = i));
+    if (plates.length === 0) {
+        // Distinguish the common user mistake: a MODEL/PROJECT 3MF (meshes, no
+        // sliced G-code) vs a genuinely empty/unrecognized archive. Slicing is a
+        // slicer's job — tell the user what to export instead.
+        const isModelProject = dir.entries.some((e) => e.name === '3d/3dmodel.model');
+        throw new ContainerError('E_CONTAINER_NO_PAYLOAD', isModelProject
+            ? 'this is a model/project 3MF (3D meshes, no sliced G-code). The viewer displays sliced output — ' +
+                'in Bambu Studio/OrcaSlicer, slice the plate and use "Export plate sliced file" (.gcode.3mf)'
+            : 'no Metadata/plate_*.gcode entries found');
+    }
+    // Amendment 3: a duplicate of a SELECTED PAYLOAD name is an error, not a warning.
+    const payloadDup = warnings.find((w) => w.code === 'container-duplicate-entry' && plates.some((p) => w.message.includes(`'${canonicalName(p.name)}'`)));
+    if (payloadDup !== undefined) {
+        throw new ContainerError('E_CONTAINER_DUPLICATE', payloadDup.message);
+    }
+    // Bounded metadata extraction (discovery-time; small entries only).
+    const raw = {};
+    let machine;
+    let filaments;
+    const settingsEntry = dir.entries.find((e) => e.name === 'metadata/project_settings.config');
+    if (settingsEntry !== undefined) {
+        if (settingsEntry.uncompressedSize > limits.maxMetadataBytes) {
+            warnings.push({
+                code: 'metadata-truncated',
+                message: 'project_settings.config exceeds maxMetadataBytes; skipped'
+            });
+        }
+        else {
+            try {
+                const text = new TextDecoder().decode(await extractEntry(bytes, settingsEntry, limits.maxMetadataBytes));
+                const settings = JSON.parse(text);
+                machine = machineFromSettings(settings);
+                filaments = filamentsFromSettings(settings);
+                for (const key of RAW_WHITELIST) {
+                    const v = settings[key];
+                    if (typeof v === 'string' || typeof v === 'number')
+                        raw[key] = String(v).slice(0, 4096);
+                    else if (Array.isArray(v))
+                        raw[key] = v.slice(0, 64).join(',').slice(0, 4096);
+                }
+            }
+            catch (err) {
+                warnings.push({
+                    code: 'container-metadata-invalid',
+                    message: `project_settings.config unreadable: ${err instanceof Error ? err.message : err}`
+                });
+            }
+        }
+    }
+    return {
+        id: 'gcode-3mf',
+        plates: plates.map(({ index, name, estimatedBytes }) => ({ index, name, estimatedBytes })),
+        metadata: { machine, filaments, raw, warnings },
+        openPlate(index) {
+            const plate = plates[index];
+            if (plate === undefined) {
+                throw new ContainerError('E_CONTAINER_NO_PAYLOAD', `plate ${index} does not exist (${plates.length} plates)`);
+            }
+            // Stream with incremental caps; verify CRC + size at end-of-stream.
+            const gen = streamEntry(bytes, plate.entry, limits.maxExpandedBytesPerEntry);
+            let crc = 0xffffffff;
+            let total = 0;
+            return {
+                getReader: () => ({
+                    read: async () => {
+                        const { done, value } = await gen.next();
+                        if (done) {
+                            if (crc32Final(crc) !== plate.entry.crc32) {
+                                throw new ContainerError('E_CONTAINER_CRC', `CRC mismatch for '${plate.entry.name}'`);
+                            }
+                            if (total !== plate.entry.uncompressedSize) {
+                                throw new ContainerError('E_CONTAINER_HEADER_MISMATCH', `expanded size of '${plate.entry.name}' differs from headers`);
+                            }
+                            return { done: true };
+                        }
+                        crc = crc32(value, crc);
+                        total += value.byteLength;
+                        return { done: false, value: value };
+                    }
+                })
+            };
+        }
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @chestnutlabs/gcode-containers — safe container extraction (DD-005 §4.4/§7).
+ *
+ * Phase 2 (#74): the hardened in-memory ZIP reader and the `.gcode.3mf`
+ * adapter. In-memory only, zero dependencies, never writes files, never
+ * fetches. Depends only on @chestnutlabs/toolpath-core; the parser consumes
+ * it through its structural ContainerAdapterLike type (worker entries compose).
+ */
+export { ContainerError, DEFAULT_CONTAINER_LIMITS, canonicalName, crc32, crc32Final, readDirectory, locatePayload, extractEntry, streamEntry } from './zip.js';
+export type { ContainerLimits, ZipEntry, ZipDirectory } from './zip.js';
+export { openGcode3mf, sniffGcode3mf } from './gcode-3mf.js';
+export type { OpenedContainer, PlateEntry, ContainerMetadata, StreamLike } from './gcode-3mf.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,aAAa,EACb,KAAK,EACL,UAAU,EACV,aAAa,EACb,aAAa,EACb,YAAY,EACZ,WAAW,EACZ,MAAM,UAAU,CAAC;AAClB,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC7D,YAAY,EAAE,eAAe,EAAE,UAAU,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * @chestnutlabs/gcode-containers — safe container extraction (DD-005 §4.4/§7).
+ *
+ * Phase 2 (#74): the hardened in-memory ZIP reader and the `.gcode.3mf`
+ * adapter. In-memory only, zero dependencies, never writes files, never
+ * fetches. Depends only on @chestnutlabs/toolpath-core; the parser consumes
+ * it through its structural ContainerAdapterLike type (worker entries compose).
+ */
+export { ContainerError, DEFAULT_CONTAINER_LIMITS, canonicalName, crc32, crc32Final, readDirectory, locatePayload, extractEntry, streamEntry } from './zip.js';
+export { openGcode3mf, sniffGcode3mf } from './gcode-3mf.js';

package/dist/zip.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Minimal, hostile-input-hardened ZIP reader (DD-005 §4.4/§7, as amended).
+ *
+ * In-memory only — never touches a filesystem. Zero dependencies: inflate uses
+ * the platform `DecompressionStream('deflate-raw')` (browsers, workers, and the
+ * pinned Node 22+ runtime; NOT Node 18). Enforced per amendment 3:
+ *   - per-entry CRC32 verification (streaming accumulation)
+ *   - central/local header agreement (name, sizes, method)
+ *   - encrypted-entry rejection
+ *   - duplicate canonical-name handling
+ *   - incremental expanded-byte caps (a lying header cannot balloon memory)
+ * Zip64 is detected and rejected with a structured error (v1 scope; .gcode.3mf
+ * payloads are far below 4 GB).
+ */
+export declare class ContainerError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface ContainerLimits {
+    maxEntries: number;
+    maxEntryNameBytes: number;
+    maxExpandedBytesPerEntry: number;
+    maxExpandedBytesTotal: number;
+    maxMetadataBytes: number;
+}
+/** §7.2 defaults (provisional; ratified by the E4 benchmark phase). */
+export declare const DEFAULT_CONTAINER_LIMITS: ContainerLimits;
+export interface ZipEntry {
+    /** Canonical name: forward slashes, no traversal — see canonicalName(). */
+    name: string;
+    rawName: string;
+    method: number;
+    compressedSize: number;
+    uncompressedSize: number;
+    crc32: number;
+    localHeaderOffset: number;
+    flags: number;
+}
+export declare function crc32(bytes: Uint8Array, seed?: number): number;
+export declare const crc32Final: (c: number) => number;
+/**
+ * Canonicalize an entry name for duplicate detection and selection sanity:
+ * backslashes → slashes, case-folded, collapsed slashes. Returns null for
+ * HOSTILE names (traversal segments, absolute paths, drive letters, NUL).
+ */
+export declare function canonicalName(rawName: string): string | null;
+export interface ZipDirectory {
+    /** Central-directory entries in CD order, hostile names excluded (warned). */
+    entries: ZipEntry[];
+    warnings: {
+        code: string;
+        message: string;
+    }[];
+}
+/** Parse the central directory (discovery only — no payload inflate). */
+export declare function readDirectory(bytes: Uint8Array, limits: ContainerLimits): ZipDirectory;
+/** Validate central/local header agreement and return the payload data offset. */
+export declare function locatePayload(bytes: Uint8Array, entry: ZipEntry): number;
+/**
+ * Extract one entry fully in memory with incremental caps + streaming CRC.
+ * `cap` bounds the expanded size REGARDLESS of what headers claim.
+ */
+export declare function extractEntry(bytes: Uint8Array, entry: ZipEntry, cap: number): Promise<Uint8Array>;
+/**
+ * Stream an entry's expanded bytes with an incremental cap. CRC verification
+ * for the streaming path is the CALLER's job via crc32/crc32Final (the plate
+ * pipeline verifies at end-of-stream); extractEntry() verifies internally.
+ */
+export declare function streamEntry(bytes: Uint8Array, entry: ZipEntry, cap: number): AsyncGenerator<Uint8Array>;
+//# sourceMappingURL=zip.d.ts.map

package/dist/zip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip.d.ts","sourceRoot":"","sources":["../src/zip.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,qBAAa,cAAe,SAAQ,KAAK;aAErB,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAC5B,OAAO,EAAE,MAAM;CAKlB;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wBAAwB,EAAE,MAAM,CAAC;IACjC,qBAAqB,EAAE,MAAM,CAAC;IAC9B,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,uEAAuE;AACvE,eAAO,MAAM,wBAAwB,EAAE,eAMtC,CAAC;AAEF,MAAM,WAAW,QAAQ;IACvB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;CACf;AAkBD,wBAAgB,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,SAAa,GAAG,MAAM,CAMlE;AAED,eAAO,MAAM,UAAU,GAAI,GAAG,MAAM,KAAG,MAAgC,CAAC;AAExE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAQ5D;AASD,MAAM,WAAW,YAAY;IAC3B,8EAA8E;IAC9E,OAAO,EAAE,QAAQ,EAAE,CAAC;IACpB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C;AAED,yEAAyE;AACzE,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,GAAG,YAAY,CA8EtF;AAED,kFAAkF;AAClF,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,GAAG,MAAM,CAwCxE;AAID;;;GAGG;AACH,wBAAsB,YAAY,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAsBvG;AAED;;;;GAIG;AACH,wBAAuB,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,cAAc,CAAC,UAAU,CAAC,CAiE9G"}

package/dist/zip.js

@@ -0,0 +1,283 @@
+/**
+ * Minimal, hostile-input-hardened ZIP reader (DD-005 §4.4/§7, as amended).
+ *
+ * In-memory only — never touches a filesystem. Zero dependencies: inflate uses
+ * the platform `DecompressionStream('deflate-raw')` (browsers, workers, and the
+ * pinned Node 22+ runtime; NOT Node 18). Enforced per amendment 3:
+ *   - per-entry CRC32 verification (streaming accumulation)
+ *   - central/local header agreement (name, sizes, method)
+ *   - encrypted-entry rejection
+ *   - duplicate canonical-name handling
+ *   - incremental expanded-byte caps (a lying header cannot balloon memory)
+ * Zip64 is detected and rejected with a structured error (v1 scope; .gcode.3mf
+ * payloads are far below 4 GB).
+ */
+export class ContainerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ContainerError';
+    }
+}
+/** §7.2 defaults (provisional; ratified by the E4 benchmark phase). */
+export const DEFAULT_CONTAINER_LIMITS = {
+    maxEntries: 4096,
+    maxEntryNameBytes: 1024,
+    maxExpandedBytesPerEntry: 512 * 1024 * 1024,
+    maxExpandedBytesTotal: 1024 * 1024 * 1024,
+    maxMetadataBytes: 8 * 1024 * 1024
+};
+const EOCD_SIG = 0x06054b50;
+const CD_SIG = 0x02014b50;
+const LOCAL_SIG = 0x04034b50;
+const ZIP64_EOCD_SIG = 0x06064b50;
+/** CRC32 (IEEE) with the standard table. */
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+export function crc32(bytes, seed = 0xffffffff) {
+    let c = seed;
+    for (let i = 0; i < bytes.length; i++) {
+        c = CRC_TABLE[(c ^ bytes[i]) & 0xff] ^ (c >>> 8);
+    }
+    return c >>> 0;
+}
+export const crc32Final = (c) => (c ^ 0xffffffff) >>> 0;
+/**
+ * Canonicalize an entry name for duplicate detection and selection sanity:
+ * backslashes → slashes, case-folded, collapsed slashes. Returns null for
+ * HOSTILE names (traversal segments, absolute paths, drive letters, NUL).
+ */
+export function canonicalName(rawName) {
+    if (rawName.includes('\0'))
+        return null;
+    const slashed = rawName.replace(/\\/g, '/');
+    if (/^[a-zA-Z]:/.test(slashed) || slashed.startsWith('/'))
+        return null;
+    const parts = slashed.split('/').filter((p) => p.length > 0);
+    if (parts.some((p) => p === '..' || p === '.'))
+        return null;
+    if (parts.length === 0)
+        return null;
+    return parts.join('/').toLowerCase();
+}
+function u16(b, o) {
+    return b[o] | (b[o + 1] << 8);
+}
+function u32(b, o) {
+    return (b[o] | (b[o + 1] << 8) | (b[o + 2] << 16) | (b[o + 3] << 24)) >>> 0;
+}
+/** Parse the central directory (discovery only — no payload inflate). */
+export function readDirectory(bytes, limits) {
+    // Locate EOCD: scan backward over the last 64KB+22 for the signature.
+    const scanStart = Math.max(0, bytes.length - (64 * 1024 + 22));
+    let eocd = -1;
+    for (let i = bytes.length - 22; i >= scanStart; i--) {
+        if (u32(bytes, i) === EOCD_SIG) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd === -1)
+        throw new ContainerError('E_CONTAINER_FORMAT', 'not a ZIP archive (no end-of-central-directory)');
+    const totalEntries = u16(bytes, eocd + 10);
+    const cdSize = u32(bytes, eocd + 12);
+    const cdOffset = u32(bytes, eocd + 16);
+    if (totalEntries === 0xffff || cdOffset === 0xffffffff || cdSize === 0xffffffff) {
+        throw new ContainerError('E_CONTAINER_ZIP64', 'zip64 archives are not supported (v1 scope)');
+    }
+    // Explicit zip64 EOCD present anywhere near the tail → reject rather than misparse.
+    for (let i = Math.max(0, eocd - 76); i < eocd; i++) {
+        if (u32(bytes, i) === ZIP64_EOCD_SIG) {
+            throw new ContainerError('E_CONTAINER_ZIP64', 'zip64 archives are not supported (v1 scope)');
+        }
+    }
+    if (totalEntries > limits.maxEntries) {
+        throw new ContainerError('E_CONTAINER_LIMIT_ENTRIES', `archive has ${totalEntries} entries (> ${limits.maxEntries})`);
+    }
+    if (cdOffset + cdSize > bytes.length) {
+        throw new ContainerError('E_CONTAINER_FORMAT', 'central directory extends past the archive');
+    }
+    const warnings = [];
+    const entries = [];
+    const seen = new Map();
+    let o = cdOffset;
+    const dec = new TextDecoder();
+    for (let n = 0; n < totalEntries; n++) {
+        if (o + 46 > bytes.length || u32(bytes, o) !== CD_SIG) {
+            throw new ContainerError('E_CONTAINER_FORMAT', `malformed central directory at entry ${n}`);
+        }
+        const flags = u16(bytes, o + 8);
+        const method = u16(bytes, o + 10);
+        const crc = u32(bytes, o + 16);
+        const compressedSize = u32(bytes, o + 20);
+        const uncompressedSize = u32(bytes, o + 24);
+        const nameLen = u16(bytes, o + 28);
+        const extraLen = u16(bytes, o + 30);
+        const commentLen = u16(bytes, o + 32);
+        const localHeaderOffset = u32(bytes, o + 42);
+        if (nameLen > limits.maxEntryNameBytes) {
+            throw new ContainerError('E_CONTAINER_LIMIT_NAME', `entry name of ${nameLen} B (> ${limits.maxEntryNameBytes})`);
+        }
+        if (compressedSize === 0xffffffff || uncompressedSize === 0xffffffff || localHeaderOffset === 0xffffffff) {
+            throw new ContainerError('E_CONTAINER_ZIP64', 'zip64 entry fields are not supported (v1 scope)');
+        }
+        const rawName = dec.decode(bytes.subarray(o + 46, o + 46 + nameLen));
+        o += 46 + nameLen + extraLen + commentLen;
+        if (rawName.endsWith('/'))
+            continue; // directory entries carry no payload
+        const name = canonicalName(rawName);
+        if (name === null) {
+            warnings.push({
+                code: 'container-entry-hostile-name',
+                message: `entry name rejected: ${JSON.stringify(rawName)}`
+            });
+            continue;
+        }
+        const dup = seen.get(name);
+        if (dup !== undefined) {
+            warnings.push({ code: 'container-duplicate-entry', message: `duplicate canonical name '${name}' (first wins)` });
+            continue; // amendment 3: first central-directory occurrence wins for metadata; payload dups error at selection
+        }
+        seen.set(name, entries.length);
+        entries.push({ name, rawName, method, compressedSize, uncompressedSize, crc32: crc, localHeaderOffset, flags });
+    }
+    return { entries, warnings };
+}
+/** Validate central/local header agreement and return the payload data offset. */
+export function locatePayload(bytes, entry) {
+    const o = entry.localHeaderOffset;
+    if (o + 30 > bytes.length || u32(bytes, o) !== LOCAL_SIG) {
+        throw new ContainerError('E_CONTAINER_FORMAT', `bad local header for '${entry.name}'`);
+    }
+    const flags = u16(bytes, o + 6);
+    if ((flags & 0x1) !== 0 || (entry.flags & 0x1) !== 0) {
+        throw new ContainerError('E_CONTAINER_ENCRYPTED', `entry '${entry.name}' is encrypted — no decryption path exists`);
+    }
+    const method = u16(bytes, o + 8);
+    const nameLen = u16(bytes, o + 26);
+    const extraLen = u16(bytes, o + 28);
+    const localName = new TextDecoder().decode(bytes.subarray(o + 30, o + 30 + nameLen));
+    if (method !== entry.method || localName !== entry.rawName) {
+        throw new ContainerError('E_CONTAINER_HEADER_MISMATCH', `central/local header disagreement for '${entry.name}' — treating the entry as hostile`);
+    }
+    // When the local header carries sizes (no data-descriptor flag), they must agree too.
+    if ((flags & 0x8) === 0) {
+        const localCrc = u32(bytes, o + 14);
+        const localCompressed = u32(bytes, o + 18);
+        const localUncompressed = u32(bytes, o + 22);
+        if (localCrc !== entry.crc32 ||
+            localCompressed !== entry.compressedSize ||
+            localUncompressed !== entry.uncompressedSize) {
+            throw new ContainerError('E_CONTAINER_HEADER_MISMATCH', `central/local size/CRC disagreement for '${entry.name}' — treating the entry as hostile`);
+        }
+    }
+    const dataStart = o + 30 + nameLen + extraLen;
+    if (dataStart + entry.compressedSize > bytes.length) {
+        throw new ContainerError('E_CONTAINER_FORMAT', `entry '${entry.name}' payload extends past the archive`);
+    }
+    return dataStart;
+}
+const INFLATE_CHUNK = 256 * 1024;
+/**
+ * Extract one entry fully in memory with incremental caps + streaming CRC.
+ * `cap` bounds the expanded size REGARDLESS of what headers claim.
+ */
+export async function extractEntry(bytes, entry, cap) {
+    const out = [];
+    let total = 0;
+    let crc = 0xffffffff;
+    for await (const chunk of streamEntry(bytes, entry, cap)) {
+        out.push(chunk);
+        total += chunk.byteLength;
+        crc = crc32(chunk, crc);
+    }
+    if (crc32Final(crc) !== entry.crc32) {
+        throw new ContainerError('E_CONTAINER_CRC', `CRC mismatch for '${entry.name}'`);
+    }
+    if (total !== entry.uncompressedSize) {
+        throw new ContainerError('E_CONTAINER_HEADER_MISMATCH', `expanded size of '${entry.name}' differs from headers`);
+    }
+    const joined = new Uint8Array(total);
+    let off = 0;
+    for (const c of out) {
+        joined.set(c, off);
+        off += c.byteLength;
+    }
+    return joined;
+}
+/**
+ * Stream an entry's expanded bytes with an incremental cap. CRC verification
+ * for the streaming path is the CALLER's job via crc32/crc32Final (the plate
+ * pipeline verifies at end-of-stream); extractEntry() verifies internally.
+ */
+export async function* streamEntry(bytes, entry, cap) {
+    const dataStart = locatePayload(bytes, entry);
+    const compressed = bytes.subarray(dataStart, dataStart + entry.compressedSize);
+    if (entry.uncompressedSize > cap) {
+        throw new ContainerError('E_CONTAINER_LIMIT_EXPANDED', `entry '${entry.name}' claims ${entry.uncompressedSize} B (> cap ${cap})`);
+    }
+    let produced = 0;
+    const guard = (chunk) => {
+        produced += chunk.byteLength;
+        if (produced > cap) {
+            throw new ContainerError('E_CONTAINER_LIMIT_EXPANDED', `entry '${entry.name}' expanded past ${cap} B — headers lied; extraction stopped`);
+        }
+        return chunk;
+    };
+    if (entry.method === 0) {
+        if (compressed.byteLength !== entry.uncompressedSize) {
+            throw new ContainerError('E_CONTAINER_HEADER_MISMATCH', `stored entry '${entry.name}' size disagreement`);
+        }
+        for (let o = 0; o < compressed.byteLength; o += INFLATE_CHUNK) {
+            yield guard(compressed.subarray(o, Math.min(o + INFLATE_CHUNK, compressed.byteLength)));
+        }
+        return;
+    }
+    if (entry.method !== 8) {
+        throw new ContainerError('E_CONTAINER_METHOD', `entry '${entry.name}' uses unsupported method ${entry.method}`);
+    }
+    const ds = new DecompressionStream('deflate-raw');
+    const writer = ds.writable.getWriter();
+    const reader = ds.readable.getReader();
+    // The writer side must never become an unobserved rejection: on corrupt
+    // deflate data the stream errors BOTH ends, and an unawaited writer promise
+    // crashes the process as an unhandled rejection even though the reader path
+    // converts its copy of the error (found by the #131 fuzzer — see the
+    // fuzz-regressions corpus). Capture instead of floating.
+    let writeError;
+    const writeAll = (async () => {
+        for (let o = 0; o < compressed.byteLength; o += INFLATE_CHUNK) {
+            await writer.write(compressed.subarray(o, Math.min(o + INFLATE_CHUNK, compressed.byteLength)));
+        }
+        await writer.close();
+    })().catch((e) => {
+        writeError = e;
+    });
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            if (value !== undefined && value.byteLength > 0)
+                yield guard(value);
+        }
+        await writeAll;
+        if (writeError !== undefined)
+            throw writeError;
+    }
+    catch (err) {
+        await writeAll; // settled by construction; never rejects
+        if (err instanceof ContainerError)
+            throw err;
+        throw new ContainerError('E_CONTAINER_INFLATE', `inflate failed for '${entry.name}': ${err instanceof Error ? err.message : err}`);
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@chestnutlabs/gcode-containers",
+  "version": "0.1.0",
+  "description": "Safe, bounded, in-memory container extraction for sliced G-code (.gcode.3mf) \u2014 DD-005 \u00a74.4/\u00a77. Never writes files, never fetches, zero dependencies.",
+  "keywords": [
+    "gcode",
+    "3d-printing",
+    "toolpath",
+    "cnc",
+    "chestnutlabs",
+    "3mf",
+    "zip",
+    "container",
+    "gcode-3mf"
+  ],
+  "author": "Chestnut Labs",
+  "homepage": "https://github.com/ChestnutLabs/gcode-preview#readme",
+  "bugs": "https://github.com/ChestnutLabs/gcode-preview/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ChestnutLabs/gcode-preview.git",
+    "directory": "packages/gcode-containers"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@chestnutlabs/toolpath-core": "0.1.0"
+  }
+}