@lp-labs/archive-stream 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Libin Prasanth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,87 @@
-# Temporary Holding Version
+# @lp-labs/archive-stream
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Standards-compatible streaming stored ZIP writing and bounded buffered ZIP extraction.
+
+Original independent MIT TypeScript implementation with **zero runtime/peer dependencies**. ESM and CommonJS with separate declarations, Node 18+ (browser use when adapters/APIs are available). Development dependencies are not consumer runtime dependencies.
+
+## Install
+
+```sh
+npm install @lp-labs/archive-stream
+```
+
+## Complete example
+
+```js
+import assert from 'node:assert/strict';
+import { writeZip, extractZipBuffered, crc32, ArchiveStreamError } from '@lp-labs/archive-stream';
+const segments = [];
+for await (const chunk of writeZip([
+  { name: 'hello.txt', data: new TextEncoder().encode('hello') },
+]))
+  segments.push(chunk);
+const bytes = Uint8Array.from(segments.flatMap((chunk) => [...chunk]));
+const files = [];
+for await (const entry of extractZipBuffered(bytes)) files.push(entry);
+assert.equal(files[0].name, 'hello.txt');
+assert.equal(new TextDecoder().decode(files[0].data), 'hello');
+assert.equal(crc32(new TextEncoder().encode('123456789')), 0xcbf43926);
+```
+
+CommonJS exposes the same API: `const api = require('@lp-labs/archive-stream')`.
+
+## Scope, customization and performance
+
+Writer emits real ZIP method0 with UTF8 names, signed descriptors, central directory and EOCD. Input chunks max1MiB, archive64MiB, entry16MiB, entries4096, metadata4MiB defaults. Extractor explicitly buffers entire archive (peak approximately twice archive bytes plus segments), NOT streaming decompression. Supports stored-only, ASCII/UTF8 names, ordinary comments/extras and signed/unsigned descriptors. Rejects compressed/encrypted/ZIP64/multidisk/preambles/gaps/overlap. CRC checked before each yield, not all entries before first yield; stage output before activation. No filesystem writes. Path policy is basic ZIP syntax, not OS extraction containment: use a dedicated guard. Returned data slices owned separately. Cancellation cooperative between chunks; writer consumers may receive partial output on late failure.
+
+Configure explicit limits, clocks, policies and adapters through the API below. Error classes and standard TypeError/RangeError reject malformed input; adapter/handler errors propagate. Await asynchronous methods and handle rejection in your application; no success-shaped fallback on failed work. Inputs must be trusted ordinary data, not hostile proxies; adapters must meet documented atomicity, isolation and ownership contracts. This package never publishes data, loads external code or starts background services at import time.
+
+## API reference
+
+The complete exported TypeScript contract (including option defaults discussed above, method return shapes, and error codes) is included below. TypeScript users import interfaces using `import type`; JavaScript users pass matching ordinary objects. Signature optionals indicate intentionally optional fields, not silent recovery.
+
+```ts
+export type ArchiveErrorCode =
+  'invalid' | 'limit' | 'unsupported' | 'corrupt' | 'truncated' | 'crc' | 'cancelled';
+export declare class ArchiveStreamError extends Error {
+  readonly code: ArchiveErrorCode;
+  constructor(code: ArchiveErrorCode, message: string);
+}
+export interface ZipLimits {
+  maxArchiveBytes?: number;
+  maxEntryBytes?: number;
+  maxEntries?: number;
+  maxNameBytes?: number;
+  maxMetadataBytes?: number;
+  maxChunkBytes?: number;
+  signal?: AbortSignal;
+}
+export interface ZipInputEntry {
+  name: string;
+  data: Uint8Array | AsyncIterable<Uint8Array>;
+}
+export interface ZipExtractedEntry {
+  name: string;
+  data: Uint8Array;
+  crc32: number;
+}
+export declare function crc32(bytes: Uint8Array): number;
+/** Streaming stored-method ZIP writer with signed data descriptors and bounded central metadata. */
+export declare function writeZip(
+  entries: AsyncIterable<ZipInputEntry> | Iterable<ZipInputEntry>,
+  options?: ZipLimits,
+): AsyncGenerator<Uint8Array>;
+/** Intentionally buffers the entire archive before parsing; no decompression or filesystem writes. */
+export declare function extractZipBuffered(
+  source: AsyncIterable<Uint8Array> | Uint8Array,
+  options?: ZipLimits,
+): AsyncGenerator<ZipExtractedEntry>;
+```
+
+## Support
+
+If this library is useful to you, consider supporting its maintenance with a [donation via PayPal](https://www.paypal.me/LibinPrasanth).
+
+## Author
+
+Created by [Libin Prasanth](https://www.linkedin.com/in/libinprasanth/). Connect on LinkedIn for updates and discussion.

package/dist/cjs/index.d.ts

@@ -0,0 +1,28 @@
+export type ArchiveErrorCode = 'invalid' | 'limit' | 'unsupported' | 'corrupt' | 'truncated' | 'crc' | 'cancelled';
+export declare class ArchiveStreamError extends Error {
+    readonly code: ArchiveErrorCode;
+    constructor(code: ArchiveErrorCode, message: string);
+}
+export interface ZipLimits {
+    maxArchiveBytes?: number;
+    maxEntryBytes?: number;
+    maxEntries?: number;
+    maxNameBytes?: number;
+    maxMetadataBytes?: number;
+    maxChunkBytes?: number;
+    signal?: AbortSignal;
+}
+export interface ZipInputEntry {
+    name: string;
+    data: Uint8Array | AsyncIterable<Uint8Array>;
+}
+export interface ZipExtractedEntry {
+    name: string;
+    data: Uint8Array;
+    crc32: number;
+}
+export declare function crc32(bytes: Uint8Array): number;
+/** Streaming stored-method ZIP writer with signed data descriptors and bounded central metadata. */
+export declare function writeZip(entries: AsyncIterable<ZipInputEntry> | Iterable<ZipInputEntry>, options?: ZipLimits): AsyncGenerator<Uint8Array>;
+/** Intentionally buffers the entire archive before parsing; no decompression or filesystem writes. */
+export declare function extractZipBuffered(source: AsyncIterable<Uint8Array> | Uint8Array, options?: ZipLimits): AsyncGenerator<ZipExtractedEntry>;

package/dist/cjs/index.js

@@ -0,0 +1,371 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArchiveStreamError = void 0;
+exports.crc32 = crc32;
+exports.writeZip = writeZip;
+exports.extractZipBuffered = extractZipBuffered;
+class ArchiveStreamError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ArchiveStreamError';
+    }
+}
+exports.ArchiveStreamError = ArchiveStreamError;
+function fail(code, message) {
+    throw new ArchiveStreamError(code, message);
+}
+function bounds(options) {
+    const result = {
+        archive: options.maxArchiveBytes ?? 67108864,
+        entry: options.maxEntryBytes ?? 16777216,
+        entries: options.maxEntries ?? 4096,
+        name: options.maxNameBytes ?? 4096,
+        metadata: options.maxMetadataBytes ?? 4194304,
+        chunk: options.maxChunkBytes ?? 1048576,
+    };
+    for (const value of Object.values(result))
+        if (!Number.isSafeInteger(value) || value < 1)
+            fail('invalid', 'Limits must be positive safe integers');
+    if (result.archive >= 0xffffffff ||
+        result.entry >= 0xffffffff ||
+        result.entries >= 0xffff ||
+        result.name > 0xffff) {
+        fail('unsupported', 'ZIP64-sized limits are unsupported');
+    }
+    return result;
+}
+function check(signal) {
+    if (signal?.aborted)
+        fail('cancelled', 'Archive operation cancelled');
+}
+function updateCrc(crc, bytes) {
+    for (const byte of bytes) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit++)
+            crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+    }
+    return crc >>> 0;
+}
+function crc32(bytes) {
+    if (!(bytes instanceof Uint8Array))
+        fail('invalid', 'Expected Uint8Array');
+    return (updateCrc(0xffffffff, bytes) ^ 0xffffffff) >>> 0;
+}
+function header(size) {
+    const bytes = new Uint8Array(size);
+    return { bytes, view: new DataView(bytes.buffer) };
+}
+function nameBytes(name, bound) {
+    if (typeof name !== 'string' ||
+        !name ||
+        name.startsWith('/') ||
+        name.includes('\\') ||
+        name.includes('\0') ||
+        /^[A-Za-z]:/.test(name) ||
+        name
+            .split('/')
+            .some((part, index, array) => part === '..' || part === '.' || (!part && index !== array.length - 1))) {
+        fail('invalid', 'Unsafe or invalid archive path');
+    }
+    const bytes = new TextEncoder().encode(name);
+    if (new TextDecoder('utf-8', { fatal: true }).decode(bytes) !== name)
+        fail('invalid', 'Name has unpaired Unicode surrogates');
+    if (bytes.length > bound.name)
+        fail('limit', 'Name byte bound exceeded');
+    return bytes;
+}
+/** Streaming stored-method ZIP writer with signed data descriptors and bounded central metadata. */
+async function* writeZip(entries, options = {}) {
+    const bound = bounds(options);
+    const records = [];
+    const names = new Set();
+    let offset = 0, metadata = 0;
+    function emit(bytes) {
+        check(options.signal);
+        if (offset + bytes.length > bound.archive)
+            fail('limit', 'Archive byte bound exceeded');
+        offset += bytes.length;
+        return bytes;
+    }
+    for await (const entry of entries) {
+        check(options.signal);
+        if (records.length >= bound.entries)
+            fail('limit', 'Entry count exceeded');
+        const name = nameBytes(entry.name, bound);
+        if (names.has(entry.name))
+            fail('invalid', 'Duplicate archive path');
+        names.add(entry.name);
+        metadata += 46 + name.length;
+        if (metadata > bound.metadata)
+            fail('limit', 'Central metadata bound exceeded');
+        const start = offset;
+        const local = header(30 + name.length);
+        local.view.setUint32(0, 0x04034b50, true);
+        local.view.setUint16(4, 20, true);
+        local.view.setUint16(6, 0x0808, true);
+        local.view.setUint16(12, 0x0021, true);
+        local.view.setUint16(26, name.length, true);
+        local.bytes.set(name, 30);
+        yield emit(local.bytes);
+        let size = 0, crc = 0xffffffff;
+        const data = entry.data;
+        const source = data instanceof Uint8Array
+            ? (async function* () {
+                for (let i = 0; i < data.length; i += bound.chunk)
+                    yield data.subarray(i, i + bound.chunk);
+            })()
+            : data;
+        for await (const chunk of source) {
+            check(options.signal);
+            if (!(chunk instanceof Uint8Array))
+                fail('invalid', 'Entry source must yield Uint8Array');
+            if (chunk.length > bound.chunk || size + chunk.length > bound.entry)
+                fail('limit', 'Entry or input chunk bound exceeded');
+            if (entry.name.endsWith('/') && chunk.length)
+                fail('invalid', 'Directory must have empty data');
+            const bytes = chunk.slice();
+            size += bytes.length;
+            crc = updateCrc(crc, bytes);
+            yield emit(bytes);
+        }
+        crc = (crc ^ 0xffffffff) >>> 0;
+        const descriptor = header(16);
+        descriptor.view.setUint32(0, 0x08074b50, true);
+        descriptor.view.setUint32(4, crc, true);
+        descriptor.view.setUint32(8, size, true);
+        descriptor.view.setUint32(12, size, true);
+        yield emit(descriptor.bytes);
+        records.push({ name, crc, size, offset: start });
+    }
+    const centralOffset = offset;
+    for (const record of records) {
+        const central = header(46 + record.name.length);
+        central.view.setUint32(0, 0x02014b50, true);
+        central.view.setUint16(4, 20, true);
+        central.view.setUint16(6, 20, true);
+        central.view.setUint16(8, 0x0808, true);
+        central.view.setUint16(14, 0x0021, true);
+        central.view.setUint32(16, record.crc, true);
+        central.view.setUint32(20, record.size, true);
+        central.view.setUint32(24, record.size, true);
+        central.view.setUint16(28, record.name.length, true);
+        central.view.setUint32(42, record.offset, true);
+        central.bytes.set(record.name, 46);
+        yield emit(central.bytes);
+    }
+    const centralSize = offset - centralOffset;
+    const end = header(22);
+    end.view.setUint32(0, 0x06054b50, true);
+    end.view.setUint16(8, records.length, true);
+    end.view.setUint16(10, records.length, true);
+    end.view.setUint32(12, centralSize, true);
+    end.view.setUint32(16, centralOffset, true);
+    yield emit(end.bytes);
+}
+/** Intentionally buffers the entire archive before parsing; no decompression or filesystem writes. */
+async function* extractZipBuffered(source, options = {}) {
+    const bound = bounds(options);
+    check(options.signal);
+    const segments = [];
+    let length = 0;
+    if (source instanceof Uint8Array) {
+        if (source.length > bound.archive)
+            fail('limit', 'Archive byte bound exceeded');
+        segments.push(source.slice());
+        length = source.length;
+    }
+    else {
+        for await (const chunk of source) {
+            check(options.signal);
+            if (!(chunk instanceof Uint8Array))
+                fail('invalid', 'Archive source must yield Uint8Array');
+            if (chunk.length > bound.chunk || length + chunk.length > bound.archive)
+                fail('limit', 'Archive or input chunk bound exceeded');
+            if (chunk.length)
+                segments.push(chunk.slice());
+            length += chunk.length;
+        }
+    }
+    check(options.signal);
+    if (length < 22)
+        fail('truncated', 'Missing ZIP end record');
+    const bytes = new Uint8Array(length);
+    let cursor = 0;
+    for (const chunk of segments) {
+        bytes.set(chunk, cursor);
+        cursor += chunk.length;
+    }
+    segments.length = 0;
+    const view = new DataView(bytes.buffer);
+    function need(at, size) {
+        if (!Number.isSafeInteger(at) || at < 0 || at + size > length)
+            fail('truncated', 'ZIP record exceeds archive');
+    }
+    function u16(at) {
+        need(at, 2);
+        return view.getUint16(at, true);
+    }
+    function u32(at) {
+        need(at, 4);
+        return view.getUint32(at, true);
+    }
+    let end = -1;
+    for (let i = length - 22; i >= Math.max(0, length - 65557); i--) {
+        if (u32(i) === 0x06054b50 && i + 22 + u16(i + 20) === length) {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0)
+        fail('truncated', 'Missing or truncated ZIP end record');
+    if (u16(end + 4) !== 0 || u16(end + 6) !== 0 || u16(end + 8) !== u16(end + 10))
+        fail('unsupported', 'Multidisk ZIP unsupported');
+    const count = u16(end + 10), centralSize = u32(end + 12), centralOffset = u32(end + 16);
+    if (count === 0xffff ||
+        centralSize === 0xffffffff ||
+        centralOffset === 0xffffffff ||
+        (end >= 20 && u32(end - 20) === 0x07064b50))
+        fail('unsupported', 'ZIP64 unsupported');
+    if (count > bound.entries || centralSize > bound.metadata)
+        fail('limit', 'Central directory bound exceeded');
+    if (centralOffset + centralSize !== end)
+        fail('corrupt', 'Central directory does not end at EOCD');
+    need(centralOffset, centralSize);
+    function extra(at, size) {
+        const stop = at + size;
+        while (at < stop) {
+            if (at + 4 > stop)
+                fail('corrupt', 'Malformed extra field');
+            const tag = u16(at), size = u16(at + 2);
+            if (tag === 1)
+                fail('unsupported', 'ZIP64 extra field unsupported');
+            at += 4 + size;
+            if (at > stop)
+                fail('corrupt', 'Truncated extra field');
+        }
+    }
+    function flags(value, method, version) {
+        if (method !== 0)
+            fail('unsupported', 'Only stored-method ZIP supported');
+        if (value & 1)
+            fail('unsupported', 'Encrypted ZIP unsupported');
+        if ((value & ~0x0808) !== 0 || version > 20)
+            fail('unsupported', 'Unsupported ZIP flags or version');
+    }
+    const records = [];
+    const names = new Set();
+    cursor = centralOffset;
+    for (let i = 0; i < count; i++) {
+        check(options.signal);
+        need(cursor, 46);
+        if (u32(cursor) !== 0x02014b50)
+            fail('corrupt', 'Invalid central directory signature');
+        const flag = u16(cursor + 8), method = u16(cursor + 10);
+        flags(flag, method, u16(cursor + 6));
+        const crc = u32(cursor + 16), compressed = u32(cursor + 20), size = u32(cursor + 24);
+        const nameLength = u16(cursor + 28), extraLength = u16(cursor + 30), commentLength = u16(cursor + 32);
+        const offset = u32(cursor + 42);
+        if (compressed === 0xffffffff || size === 0xffffffff || offset === 0xffffffff)
+            fail('unsupported', 'ZIP64 entry unsupported');
+        if (u16(cursor + 34) !== 0)
+            fail('unsupported', 'Multidisk entry unsupported');
+        if (compressed !== size)
+            fail('corrupt', 'Stored sizes must match');
+        if (size > bound.entry || nameLength > bound.name)
+            fail('limit', 'Entry bound exceeded');
+        const next = cursor + 46 + nameLength + extraLength + commentLength;
+        if (next > end)
+            fail('corrupt', 'Central record exceeds directory');
+        const encoded = bytes.subarray(cursor + 46, cursor + 46 + nameLength);
+        if (!(flag & 0x800) && encoded.some((byte) => byte >= 128))
+            fail('unsupported', 'Non-UTF8 non-ASCII filenames unsupported');
+        let name;
+        try {
+            name = new TextDecoder('utf-8', { fatal: true }).decode(encoded);
+        }
+        catch {
+            return fail('corrupt', 'Invalid UTF-8 filename');
+        }
+        nameBytes(name, bound);
+        if (names.has(name))
+            fail('corrupt', 'Duplicate archive path');
+        names.add(name);
+        extra(cursor + 46 + nameLength, extraLength);
+        records.push({ name, encoded, flags: flag, crc, size, offset, dataStart: 0, end: 0 });
+        cursor = next;
+    }
+    if (cursor !== end)
+        fail('corrupt', 'Central directory count or size mismatch');
+    const ordered = [...records].sort((a, b) => a.offset - b.offset);
+    let localEnd = 0;
+    for (const record of ordered) {
+        check(options.signal);
+        const at = record.offset;
+        if (at !== localEnd)
+            fail('corrupt', 'Overlapping entries, gaps, or preamble unsupported');
+        need(at, 30);
+        if (u32(at) !== 0x04034b50)
+            fail('corrupt', 'Invalid local header signature');
+        flags(u16(at + 6), u16(at + 8), u16(at + 4));
+        if (u16(at + 6) !== record.flags)
+            fail('corrupt', 'Local flags mismatch');
+        const nl = u16(at + 26), el = u16(at + 28);
+        need(at + 30, nl + el);
+        if (nl !== record.encoded.length ||
+            record.encoded.some((byte, index) => bytes[at + 30 + index] !== byte))
+            fail('corrupt', 'Local filename mismatch');
+        extra(at + 30 + nl, el);
+        const start = at + 30 + nl + el, stop = start + record.size;
+        if (stop > centralOffset)
+            fail('truncated', 'Entry data exceeds local region');
+        if (record.name.endsWith('/') && record.size)
+            fail('corrupt', 'Directory contains data');
+        if (!(record.flags & 8)) {
+            if (u32(at + 14) !== record.crc ||
+                u32(at + 18) !== record.size ||
+                u32(at + 22) !== record.size)
+                fail('corrupt', 'Local CRC or sizes mismatch');
+            localEnd = stop;
+        }
+        else {
+            if ((u32(at + 14) !== 0 && u32(at + 14) !== record.crc) ||
+                (u32(at + 18) !== 0 && u32(at + 18) !== record.size) ||
+                (u32(at + 22) !== 0 && u32(at + 22) !== record.size))
+                fail('corrupt', 'Descriptor local values mismatch');
+            let descriptorSize = 0;
+            if (stop + 16 <= centralOffset &&
+                u32(stop) === 0x08074b50 &&
+                u32(stop + 4) === record.crc &&
+                u32(stop + 8) === record.size &&
+                u32(stop + 12) === record.size)
+                descriptorSize = 16;
+            else if (stop + 12 <= centralOffset &&
+                u32(stop) === record.crc &&
+                u32(stop + 4) === record.size &&
+                u32(stop + 8) === record.size)
+                descriptorSize = 12;
+            else
+                fail('corrupt', 'Missing or invalid data descriptor');
+            localEnd = stop + descriptorSize;
+        }
+        record.dataStart = start;
+        record.end = stop;
+    }
+    if (localEnd !== centralOffset)
+        fail('corrupt', 'Local region and central directory mismatch');
+    for (const record of records) {
+        check(options.signal);
+        const data = bytes.subarray(record.dataStart, record.end);
+        // Check incrementally to bound cancellation latency for large entries.
+        let crc = 0xffffffff;
+        for (let i = 0; i < data.length; i += bound.chunk) {
+            check(options.signal);
+            crc = updateCrc(crc, data.subarray(i, i + bound.chunk));
+        }
+        if ((crc ^ 0xffffffff) >>> 0 !== record.crc)
+            fail('crc', 'Entry CRC32 mismatch');
+        yield { name: record.name, data: data.slice(), crc32: record.crc };
+    }
+}

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/index.d.ts

@@ -0,0 +1,28 @@
+export type ArchiveErrorCode = 'invalid' | 'limit' | 'unsupported' | 'corrupt' | 'truncated' | 'crc' | 'cancelled';
+export declare class ArchiveStreamError extends Error {
+    readonly code: ArchiveErrorCode;
+    constructor(code: ArchiveErrorCode, message: string);
+}
+export interface ZipLimits {
+    maxArchiveBytes?: number;
+    maxEntryBytes?: number;
+    maxEntries?: number;
+    maxNameBytes?: number;
+    maxMetadataBytes?: number;
+    maxChunkBytes?: number;
+    signal?: AbortSignal;
+}
+export interface ZipInputEntry {
+    name: string;
+    data: Uint8Array | AsyncIterable<Uint8Array>;
+}
+export interface ZipExtractedEntry {
+    name: string;
+    data: Uint8Array;
+    crc32: number;
+}
+export declare function crc32(bytes: Uint8Array): number;
+/** Streaming stored-method ZIP writer with signed data descriptors and bounded central metadata. */
+export declare function writeZip(entries: AsyncIterable<ZipInputEntry> | Iterable<ZipInputEntry>, options?: ZipLimits): AsyncGenerator<Uint8Array>;
+/** Intentionally buffers the entire archive before parsing; no decompression or filesystem writes. */
+export declare function extractZipBuffered(source: AsyncIterable<Uint8Array> | Uint8Array, options?: ZipLimits): AsyncGenerator<ZipExtractedEntry>;

package/dist/esm/index.js

@@ -0,0 +1,364 @@
+export class ArchiveStreamError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'ArchiveStreamError';
+    }
+}
+function fail(code, message) {
+    throw new ArchiveStreamError(code, message);
+}
+function bounds(options) {
+    const result = {
+        archive: options.maxArchiveBytes ?? 67108864,
+        entry: options.maxEntryBytes ?? 16777216,
+        entries: options.maxEntries ?? 4096,
+        name: options.maxNameBytes ?? 4096,
+        metadata: options.maxMetadataBytes ?? 4194304,
+        chunk: options.maxChunkBytes ?? 1048576,
+    };
+    for (const value of Object.values(result))
+        if (!Number.isSafeInteger(value) || value < 1)
+            fail('invalid', 'Limits must be positive safe integers');
+    if (result.archive >= 0xffffffff ||
+        result.entry >= 0xffffffff ||
+        result.entries >= 0xffff ||
+        result.name > 0xffff) {
+        fail('unsupported', 'ZIP64-sized limits are unsupported');
+    }
+    return result;
+}
+function check(signal) {
+    if (signal?.aborted)
+        fail('cancelled', 'Archive operation cancelled');
+}
+function updateCrc(crc, bytes) {
+    for (const byte of bytes) {
+        crc ^= byte;
+        for (let bit = 0; bit < 8; bit++)
+            crc = (crc >>> 1) ^ (crc & 1 ? 0xedb88320 : 0);
+    }
+    return crc >>> 0;
+}
+export function crc32(bytes) {
+    if (!(bytes instanceof Uint8Array))
+        fail('invalid', 'Expected Uint8Array');
+    return (updateCrc(0xffffffff, bytes) ^ 0xffffffff) >>> 0;
+}
+function header(size) {
+    const bytes = new Uint8Array(size);
+    return { bytes, view: new DataView(bytes.buffer) };
+}
+function nameBytes(name, bound) {
+    if (typeof name !== 'string' ||
+        !name ||
+        name.startsWith('/') ||
+        name.includes('\\') ||
+        name.includes('\0') ||
+        /^[A-Za-z]:/.test(name) ||
+        name
+            .split('/')
+            .some((part, index, array) => part === '..' || part === '.' || (!part && index !== array.length - 1))) {
+        fail('invalid', 'Unsafe or invalid archive path');
+    }
+    const bytes = new TextEncoder().encode(name);
+    if (new TextDecoder('utf-8', { fatal: true }).decode(bytes) !== name)
+        fail('invalid', 'Name has unpaired Unicode surrogates');
+    if (bytes.length > bound.name)
+        fail('limit', 'Name byte bound exceeded');
+    return bytes;
+}
+/** Streaming stored-method ZIP writer with signed data descriptors and bounded central metadata. */
+export async function* writeZip(entries, options = {}) {
+    const bound = bounds(options);
+    const records = [];
+    const names = new Set();
+    let offset = 0, metadata = 0;
+    function emit(bytes) {
+        check(options.signal);
+        if (offset + bytes.length > bound.archive)
+            fail('limit', 'Archive byte bound exceeded');
+        offset += bytes.length;
+        return bytes;
+    }
+    for await (const entry of entries) {
+        check(options.signal);
+        if (records.length >= bound.entries)
+            fail('limit', 'Entry count exceeded');
+        const name = nameBytes(entry.name, bound);
+        if (names.has(entry.name))
+            fail('invalid', 'Duplicate archive path');
+        names.add(entry.name);
+        metadata += 46 + name.length;
+        if (metadata > bound.metadata)
+            fail('limit', 'Central metadata bound exceeded');
+        const start = offset;
+        const local = header(30 + name.length);
+        local.view.setUint32(0, 0x04034b50, true);
+        local.view.setUint16(4, 20, true);
+        local.view.setUint16(6, 0x0808, true);
+        local.view.setUint16(12, 0x0021, true);
+        local.view.setUint16(26, name.length, true);
+        local.bytes.set(name, 30);
+        yield emit(local.bytes);
+        let size = 0, crc = 0xffffffff;
+        const data = entry.data;
+        const source = data instanceof Uint8Array
+            ? (async function* () {
+                for (let i = 0; i < data.length; i += bound.chunk)
+                    yield data.subarray(i, i + bound.chunk);
+            })()
+            : data;
+        for await (const chunk of source) {
+            check(options.signal);
+            if (!(chunk instanceof Uint8Array))
+                fail('invalid', 'Entry source must yield Uint8Array');
+            if (chunk.length > bound.chunk || size + chunk.length > bound.entry)
+                fail('limit', 'Entry or input chunk bound exceeded');
+            if (entry.name.endsWith('/') && chunk.length)
+                fail('invalid', 'Directory must have empty data');
+            const bytes = chunk.slice();
+            size += bytes.length;
+            crc = updateCrc(crc, bytes);
+            yield emit(bytes);
+        }
+        crc = (crc ^ 0xffffffff) >>> 0;
+        const descriptor = header(16);
+        descriptor.view.setUint32(0, 0x08074b50, true);
+        descriptor.view.setUint32(4, crc, true);
+        descriptor.view.setUint32(8, size, true);
+        descriptor.view.setUint32(12, size, true);
+        yield emit(descriptor.bytes);
+        records.push({ name, crc, size, offset: start });
+    }
+    const centralOffset = offset;
+    for (const record of records) {
+        const central = header(46 + record.name.length);
+        central.view.setUint32(0, 0x02014b50, true);
+        central.view.setUint16(4, 20, true);
+        central.view.setUint16(6, 20, true);
+        central.view.setUint16(8, 0x0808, true);
+        central.view.setUint16(14, 0x0021, true);
+        central.view.setUint32(16, record.crc, true);
+        central.view.setUint32(20, record.size, true);
+        central.view.setUint32(24, record.size, true);
+        central.view.setUint16(28, record.name.length, true);
+        central.view.setUint32(42, record.offset, true);
+        central.bytes.set(record.name, 46);
+        yield emit(central.bytes);
+    }
+    const centralSize = offset - centralOffset;
+    const end = header(22);
+    end.view.setUint32(0, 0x06054b50, true);
+    end.view.setUint16(8, records.length, true);
+    end.view.setUint16(10, records.length, true);
+    end.view.setUint32(12, centralSize, true);
+    end.view.setUint32(16, centralOffset, true);
+    yield emit(end.bytes);
+}
+/** Intentionally buffers the entire archive before parsing; no decompression or filesystem writes. */
+export async function* extractZipBuffered(source, options = {}) {
+    const bound = bounds(options);
+    check(options.signal);
+    const segments = [];
+    let length = 0;
+    if (source instanceof Uint8Array) {
+        if (source.length > bound.archive)
+            fail('limit', 'Archive byte bound exceeded');
+        segments.push(source.slice());
+        length = source.length;
+    }
+    else {
+        for await (const chunk of source) {
+            check(options.signal);
+            if (!(chunk instanceof Uint8Array))
+                fail('invalid', 'Archive source must yield Uint8Array');
+            if (chunk.length > bound.chunk || length + chunk.length > bound.archive)
+                fail('limit', 'Archive or input chunk bound exceeded');
+            if (chunk.length)
+                segments.push(chunk.slice());
+            length += chunk.length;
+        }
+    }
+    check(options.signal);
+    if (length < 22)
+        fail('truncated', 'Missing ZIP end record');
+    const bytes = new Uint8Array(length);
+    let cursor = 0;
+    for (const chunk of segments) {
+        bytes.set(chunk, cursor);
+        cursor += chunk.length;
+    }
+    segments.length = 0;
+    const view = new DataView(bytes.buffer);
+    function need(at, size) {
+        if (!Number.isSafeInteger(at) || at < 0 || at + size > length)
+            fail('truncated', 'ZIP record exceeds archive');
+    }
+    function u16(at) {
+        need(at, 2);
+        return view.getUint16(at, true);
+    }
+    function u32(at) {
+        need(at, 4);
+        return view.getUint32(at, true);
+    }
+    let end = -1;
+    for (let i = length - 22; i >= Math.max(0, length - 65557); i--) {
+        if (u32(i) === 0x06054b50 && i + 22 + u16(i + 20) === length) {
+            end = i;
+            break;
+        }
+    }
+    if (end < 0)
+        fail('truncated', 'Missing or truncated ZIP end record');
+    if (u16(end + 4) !== 0 || u16(end + 6) !== 0 || u16(end + 8) !== u16(end + 10))
+        fail('unsupported', 'Multidisk ZIP unsupported');
+    const count = u16(end + 10), centralSize = u32(end + 12), centralOffset = u32(end + 16);
+    if (count === 0xffff ||
+        centralSize === 0xffffffff ||
+        centralOffset === 0xffffffff ||
+        (end >= 20 && u32(end - 20) === 0x07064b50))
+        fail('unsupported', 'ZIP64 unsupported');
+    if (count > bound.entries || centralSize > bound.metadata)
+        fail('limit', 'Central directory bound exceeded');
+    if (centralOffset + centralSize !== end)
+        fail('corrupt', 'Central directory does not end at EOCD');
+    need(centralOffset, centralSize);
+    function extra(at, size) {
+        const stop = at + size;
+        while (at < stop) {
+            if (at + 4 > stop)
+                fail('corrupt', 'Malformed extra field');
+            const tag = u16(at), size = u16(at + 2);
+            if (tag === 1)
+                fail('unsupported', 'ZIP64 extra field unsupported');
+            at += 4 + size;
+            if (at > stop)
+                fail('corrupt', 'Truncated extra field');
+        }
+    }
+    function flags(value, method, version) {
+        if (method !== 0)
+            fail('unsupported', 'Only stored-method ZIP supported');
+        if (value & 1)
+            fail('unsupported', 'Encrypted ZIP unsupported');
+        if ((value & ~0x0808) !== 0 || version > 20)
+            fail('unsupported', 'Unsupported ZIP flags or version');
+    }
+    const records = [];
+    const names = new Set();
+    cursor = centralOffset;
+    for (let i = 0; i < count; i++) {
+        check(options.signal);
+        need(cursor, 46);
+        if (u32(cursor) !== 0x02014b50)
+            fail('corrupt', 'Invalid central directory signature');
+        const flag = u16(cursor + 8), method = u16(cursor + 10);
+        flags(flag, method, u16(cursor + 6));
+        const crc = u32(cursor + 16), compressed = u32(cursor + 20), size = u32(cursor + 24);
+        const nameLength = u16(cursor + 28), extraLength = u16(cursor + 30), commentLength = u16(cursor + 32);
+        const offset = u32(cursor + 42);
+        if (compressed === 0xffffffff || size === 0xffffffff || offset === 0xffffffff)
+            fail('unsupported', 'ZIP64 entry unsupported');
+        if (u16(cursor + 34) !== 0)
+            fail('unsupported', 'Multidisk entry unsupported');
+        if (compressed !== size)
+            fail('corrupt', 'Stored sizes must match');
+        if (size > bound.entry || nameLength > bound.name)
+            fail('limit', 'Entry bound exceeded');
+        const next = cursor + 46 + nameLength + extraLength + commentLength;
+        if (next > end)
+            fail('corrupt', 'Central record exceeds directory');
+        const encoded = bytes.subarray(cursor + 46, cursor + 46 + nameLength);
+        if (!(flag & 0x800) && encoded.some((byte) => byte >= 128))
+            fail('unsupported', 'Non-UTF8 non-ASCII filenames unsupported');
+        let name;
+        try {
+            name = new TextDecoder('utf-8', { fatal: true }).decode(encoded);
+        }
+        catch {
+            return fail('corrupt', 'Invalid UTF-8 filename');
+        }
+        nameBytes(name, bound);
+        if (names.has(name))
+            fail('corrupt', 'Duplicate archive path');
+        names.add(name);
+        extra(cursor + 46 + nameLength, extraLength);
+        records.push({ name, encoded, flags: flag, crc, size, offset, dataStart: 0, end: 0 });
+        cursor = next;
+    }
+    if (cursor !== end)
+        fail('corrupt', 'Central directory count or size mismatch');
+    const ordered = [...records].sort((a, b) => a.offset - b.offset);
+    let localEnd = 0;
+    for (const record of ordered) {
+        check(options.signal);
+        const at = record.offset;
+        if (at !== localEnd)
+            fail('corrupt', 'Overlapping entries, gaps, or preamble unsupported');
+        need(at, 30);
+        if (u32(at) !== 0x04034b50)
+            fail('corrupt', 'Invalid local header signature');
+        flags(u16(at + 6), u16(at + 8), u16(at + 4));
+        if (u16(at + 6) !== record.flags)
+            fail('corrupt', 'Local flags mismatch');
+        const nl = u16(at + 26), el = u16(at + 28);
+        need(at + 30, nl + el);
+        if (nl !== record.encoded.length ||
+            record.encoded.some((byte, index) => bytes[at + 30 + index] !== byte))
+            fail('corrupt', 'Local filename mismatch');
+        extra(at + 30 + nl, el);
+        const start = at + 30 + nl + el, stop = start + record.size;
+        if (stop > centralOffset)
+            fail('truncated', 'Entry data exceeds local region');
+        if (record.name.endsWith('/') && record.size)
+            fail('corrupt', 'Directory contains data');
+        if (!(record.flags & 8)) {
+            if (u32(at + 14) !== record.crc ||
+                u32(at + 18) !== record.size ||
+                u32(at + 22) !== record.size)
+                fail('corrupt', 'Local CRC or sizes mismatch');
+            localEnd = stop;
+        }
+        else {
+            if ((u32(at + 14) !== 0 && u32(at + 14) !== record.crc) ||
+                (u32(at + 18) !== 0 && u32(at + 18) !== record.size) ||
+                (u32(at + 22) !== 0 && u32(at + 22) !== record.size))
+                fail('corrupt', 'Descriptor local values mismatch');
+            let descriptorSize = 0;
+            if (stop + 16 <= centralOffset &&
+                u32(stop) === 0x08074b50 &&
+                u32(stop + 4) === record.crc &&
+                u32(stop + 8) === record.size &&
+                u32(stop + 12) === record.size)
+                descriptorSize = 16;
+            else if (stop + 12 <= centralOffset &&
+                u32(stop) === record.crc &&
+                u32(stop + 4) === record.size &&
+                u32(stop + 8) === record.size)
+                descriptorSize = 12;
+            else
+                fail('corrupt', 'Missing or invalid data descriptor');
+            localEnd = stop + descriptorSize;
+        }
+        record.dataStart = start;
+        record.end = stop;
+    }
+    if (localEnd !== centralOffset)
+        fail('corrupt', 'Local region and central directory mismatch');
+    for (const record of records) {
+        check(options.signal);
+        const data = bytes.subarray(record.dataStart, record.end);
+        // Check incrementally to bound cancellation latency for large entries.
+        let crc = 0xffffffff;
+        for (let i = 0; i < data.length; i += bound.chunk) {
+            check(options.signal);
+            crc = updateCrc(crc, data.subarray(i, i + bound.chunk));
+        }
+        if ((crc ^ 0xffffffff) >>> 0 !== record.crc)
+            fail('crc', 'Entry CRC32 mismatch');
+        yield { name: record.name, data: data.slice(), crc32: record.crc };
+    }
+}

package/package.json

@@ -1,6 +1,63 @@
 {
   "name": "@lp-labs/archive-stream",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Standards-compatible streaming stored ZIP writing and bounded buffered ZIP extraction.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "npm run build && node scripts/check-types.mjs",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "format": "prettier --write src scripts tests *.json README.md",
+    "format:check": "prettier --check src scripts tests *.json README.md",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "prettier": "^3.6.2"
+  },
+  "prettier": {
+    "singleQuote": true,
+    "semi": true,
+    "trailingComma": "all",
+    "printWidth": 100,
+    "endOfLine": "lf"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "author": {
+    "name": "Libin Prasanth",
+    "url": "https://www.linkedin.com/in/libinprasanth/"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.me/LibinPrasanth"
+  }
+}