@ismail-elkorchi/bytefold 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ismail El Korchi
+
+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

@@ -0,0 +1,48 @@
+---
+role: overview
+audience: users
+source_of_truth: README.md
+update_triggers:
+  - public API changes
+  - supported formats or codecs
+---
+
+# bytefold
+
+Multi-format archive reader/writer for Node 24+, Deno, Bun, and Web (Browser). ESM-only, TypeScript strict, no runtime dependencies (tests: `test/repo-invariants.test.ts`).
+
+## Install
+
+```sh
+npm install @ismail-elkorchi/bytefold
+```
+
+## Quickstart (auto-detect)
+
+```js
+import { openArchive } from '@ismail-elkorchi/bytefold';
+
+const reader = await openArchive(bytesOrStream, { profile: 'agent' });
+const report = await reader.audit({ profile: 'agent' });
+console.log(JSON.stringify(report));
+
+await reader.assertSafe({ profile: 'agent' });
+for await (const entry of reader.entries()) {
+  if (entry.isDirectory) continue;
+  const data = await new Response(await entry.open()).arrayBuffer();
+  console.log(entry.name, data.byteLength);
+}
+```
+
+Support matrix: see `SPEC.md` (Support matrix section).
+
+Web runtime entrypoint: `@ismail-elkorchi/bytefold/web` (HTTPS URL input only; full-fetch by design; no seekable HTTP range sessions in web adapter).
+
+## Verification
+`npm run check`
+
+## Docs
+- `SPEC.md` (invariants, API entrypoints, error/report model)
+- `ARCHITECTURE.md` (module map and data flow)
+- `SECURITY.md` (threat model and reporting)
+- `CONTRIBUTING.md`, `CHANGELOG.md`

package/SPEC.md

@@ -0,0 +1,285 @@
+---
+role: spec
+audience: maintainers, agents, users
+source_of_truth: SPEC.md
+update_triggers:
+  - public API changes
+  - new invariants or error codes
+  - new formats, codecs, or filters
+---
+
+# SPEC
+
+## Domain model (conceptual)
+- Archive: a container of entries (files, directories, links) that can be opened, audited, normalized, and extracted.
+- Compression: byte-level transforms for entry payloads or whole archives (e.g., deflate, zstd, xz).
+- Audit: validation pass that reports issues without mutating data.
+- Normalize: deterministic rewrite that fixes or flags issues according to a profile.
+
+## Public API entrypoints
+Snapshot enforced by `test/export-surface.test.ts` and `test/support-matrix.test.ts`.
+### npm (package.json exports)
+- `@ismail-elkorchi/bytefold`
+- `@ismail-elkorchi/bytefold/archive`
+- `@ismail-elkorchi/bytefold/compress`
+- `@ismail-elkorchi/bytefold/zip`
+- `@ismail-elkorchi/bytefold/tar`
+- `@ismail-elkorchi/bytefold/node`
+- `@ismail-elkorchi/bytefold/node/zip`
+- `@ismail-elkorchi/bytefold/deno`
+- `@ismail-elkorchi/bytefold/bun`
+- `@ismail-elkorchi/bytefold/web`
+
+### jsr (jsr.json exports)
+- `@ismail-elkorchi/bytefold`
+- `@ismail-elkorchi/bytefold/archive`
+- `@ismail-elkorchi/bytefold/compress`
+- `@ismail-elkorchi/bytefold/zip`
+- `@ismail-elkorchi/bytefold/tar`
+- `@ismail-elkorchi/bytefold/deno`
+- `@ismail-elkorchi/bytefold/bun`
+- `@ismail-elkorchi/bytefold/web`
+
+## Invariants (test-linked)
+1. Runtime dependencies count is zero; package is ESM-only and requires Node >= 24. (tests: `test/repo-invariants.test.ts`)
+2. TypeScript strict mode remains enabled. (tests: `test/repo-invariants.test.ts`)
+3. Default entrypoints do not import `node:*` at module evaluation. (tests: `test/repo-invariants.test.ts`)
+4. Emitted `Uint8Array` chunks are immutable after enqueue, including under chunking adversary inputs. (tests: `test/xz-aliasing.test.ts`, `test/deflate64-aliasing.test.ts`, `test/streaming-invariance.test.ts`)
+5. Streaming decompression is invariant to input chunking for gzip, bzip2, and xz (including BCJ). (tests: `test/streaming-invariance.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+6. Mutation harness applies deterministic byte-level mutations across bytes/stream/file/url boundaries for zip/tar/gz/bz2/xz inputs; failures surface typed errors with schema-valid `toJSON()`, successes return schema-valid audits. (tests: `test/mutation-harness.test.ts`)
+7. Third-party ZIP and TAR fixtures open, list, and audit cleanly with provenance + size bounds. (tests: `test/zip-tar-thirdparty.test.ts`, `test/third-party-provenance.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+8. Seekable ZIP preflight enforces EOCD/central-directory ceilings before full buffering, rejects multi-disk archives, and stays bounded in HTTP range requests/bytes. (tests: `test/zip-seekable-preflight.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+9. Seekable ZIP over HTTP Range is used for list + single-entry extract and stays bounded without full downloads when Range is supported (tests assert total bytes ≤ ceil(size/16) and request count ≤ 1 + ceil((size/16)/64KiB) + 2). (tests: `test/zip-url-seekable-budget.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+10. HTTP Range sessions pin validators; If-Range is sent only with strong ETags (never weak ETag/Last-Modified), 200 responses to ranged requests with If-Range are treated as resource changed, and Content-Encoding responses are rejected. Snapshot policy require-strong-etag fails without a strong validator, while best-effort proceeds without If-Range. (specs: `specs/http/rfc9110-if-range.md`, `specs/http/rfc9110-accept-encoding.md`; tests: `test/zip-url-seekable-budget.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+11. HTTP header-only range failures fail fast by aborting request bodies before payload consumption; slow-body adversarial servers remain bounded (`<= 4096` bytes served) for range-unsupported and content-encoding rejection paths. (tests: `test/zip-url-seekable-budget.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+12. HTTP 206 bodies must match the requested range length exactly; truncated or overrun bodies fail with typed bad-response errors. (tests: `test/zip-url-seekable-budget.test.ts`, `test/bun.smoke.ts`, `test/deno.smoke.ts`)
+13. Gzip header options (FEXTRA/FNAME/FCOMMENT) are parsed; FNAME yields the entry name even when extra fields are present, consistently across runtimes. (tests: `test/gzip-header-options.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+14. Gzip FHCRC headers are validated when present; mismatches throw typed errors. (tests: `test/gzip-fhcrc.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+15. Decompression output ceilings enforce `maxTotalDecompressedBytes` for gzip/deflate/brotli/zstd and fail with `COMPRESSION_RESOURCE_LIMIT` without emitting beyond the limit. (tests: `test/compression-resource-limits.test.ts`)
+16. XZ Index VLI parsing is chunk-boundary safe, including multi-byte uncompressed sizes. (tests: `test/xz-vli-boundaries.test.ts`, `test/streaming-invariance.test.ts`)
+17. XZ streaming decode supports padding + concatenation and validates checks (none/CRC32/CRC64/SHA-256). (tests: `test/xz-utils-conformance.test.ts`, `test/xz-bcj-filters.test.ts`)
+18. XZ supports filters LZMA2, Delta, BCJ x86/PowerPC/IA64/ARM/ARM-Thumb/SPARC/ARM64/RISC-V; unsupported filters/checks throw typed errors. (tests: `test/xz-utils-conformance.test.ts`, `test/xz-bcj-filters.test.ts`, `test/xz-thirdparty.test.ts`)
+19. Mixed XZ filter chains (Delta -> BCJ -> LZMA2) decode correctly with filters applied in reverse order. (tests: `test/xz-mixed-filters.test.ts`, `test/xz-seekable-preflight.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+20. XZ BCJ filters enforce property sizing/alignment and cannot be the last filter. Size-changing filters cannot be non-last. (tests: `test/xz-bcj-filters.test.ts`)
+21. XZ BCJ start offset properties are stream-relative and reset at each concatenated stream. Properties are honored per block. (tests: `test/xz-bcj-filters.test.ts`, `test/xz-concat-bcj.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+22. XZ corruption yields typed errors and extraction is atomic for corrupted streams. (tests: `test/xz.test.ts`, `test/xz-utils-conformance.test.ts`)
+23. XZ resource ceilings are enforced (buffer + dictionary + Index limits). (tests: `test/xz-utils-conformance.test.ts`, `test/xz-index-limits.test.ts`)
+24. XZ preflight scanning bounds Index parsing without per-record allocations. (tests: `test/xz-index-limits.test.ts`)
+25. Seekable XZ preflight enforces Index limits before full buffering. (tests: `test/xz-seekable-preflight.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+26. Seekable XZ preflight enforces dictionary limits before full buffering (bounded block-header scan). (tests: `test/xz-seekable-preflight.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+27. Seekable XZ preflight HTTP failures map to specific `ARCHIVE_HTTP_*` codes with `context.httpCode` preserving the originating HTTP failure class. (tests: `test/xz-http-error-mapping.test.ts`, `test/xz-seekable-preflight.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+28. Seekable XZ preflight success path is bounded in HTTP range requests/bytes and reports incomplete scans when block header limits are exceeded without blocking decode. (tests: `test/xz-seekable-preflight.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+29. Report + error JSON schemas are versioned and validated. (tests: `test/schema-contracts.test.ts`, `test/json-safety.test.ts`)
+30. Public export surface matches the manifest snapshot. (tests: `test/export-surface.test.ts`)
+31. TypeScript declaration surface for every npm/jsr public entrypoint matches the committed snapshot manifest; intentional surface breaks in ALPHA require snapshot updates and explicit CHANGELOG entries, and V1+ will introduce stricter migration discipline. (tests: `test/type-surface.test.ts`)
+32. npm pack payload obeys allowlist/denylist policy: runtime artifacts plus contract metadata (`SPEC.md`) and JSON schemas (`schemas/*.json`) only; repo-internal indexes (`docs/REPO_INDEX.*`) and internal sources are excluded. (tests: `test/packaging-contract.test.ts`, `scripts/verify-pack.mjs`)
+33. Normalize safe mode is deterministic and lossless mode preserves bytes where documented. (zip/tar idempotent.) (tests: `test/normalize.test.ts`, `test/audit-normalize-proof.test.ts`)
+34. `extractAll` blocks path traversal. Deterministic ZIP/TAR adversarial corpora also surface traversal as audit failures (`ZIP_PATH_TRAVERSAL` / `TAR_PATH_TRAVERSAL`) and fail `assertSafe` under the agent profile. (tests: `test/zip.test.ts`, `test/security-audit-simulation.test.ts`)
+35. `openArchive` auto-detects documented formats; tar.br requires an explicit hint. (tests: `test/archive.test.ts`, `test/bzip2.test.ts`, `test/xz.test.ts`, `test/tar-xz.test.ts`)
+36. Context index artifacts are deterministic and bounded: `npm run context:index` produces `docs/REPO_INDEX.md` (<= 250 KiB) plus `docs/REPO_INDEX.md.sha256` with stable sorting and no timestamps. (tests: `test/context-tools.test.ts`)
+37. Error JSON `context` never shadows top-level keys (`schemaVersion`, `name`, `code`, `message`, `hint`, `context`, plus top-level optionals such as `entryName`, `method`, `offset`, `algorithm`). (tests: `test/error-contracts.test.ts`, `test/error-json-ambiguity.test.ts`, `test/schema-contracts.test.ts`)
+38. Profile/limits precedence is deterministic across readers and decompressor setup: profile selects defaults, explicit `limits` override only provided fields, and explicit decompressor scalar limits override `limits` for matching knobs. (tests: `test/option-precedence.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+39. openArchive(...) accepts Blob/File inputs (inputKind: "blob"); ZIP on Blob is seekable via random access (slice reads) while non-ZIP Blob inputs are bounded by input limits. (tests: `test/archive.test.ts`, `test/web-adapter.test.ts`, `test/schema-contracts.test.ts`)
+40. Web adapter URL inputs (@ismail-elkorchi/bytefold/web) are HTTPS-only and always full-fetch bytes (no HTTP range sessions); the fetch path enforces input-size limits and preserves inputKind: "url". (tests: `test/web-adapter.test.ts`, `test/security-audit-simulation.test.ts`)
+41. Browser-facing entrypoint stays web-bundle safe: `npm run web:check` bundles `web/mod.ts` for `platform=browser`, rejects `node:*` imports, and is deterministic across runs. (tests: `test/web-check.test.ts`, `test/repo-invariants.test.ts`)
+42. Web entrypoint writer roundtrips are contract-backed: ZIP (store-only) and TAR archives written to Web `WritableStream` sinks can be reopened from Blob via `openArchive(...)`, preserve entry names/bytes, and remain safe under `audit` + deterministic `normalizeToWritable`. (tests: `test/web-writer-roundtrip.test.ts`)
+43. TAR octal parsing uses null-terminated UTF-8 decoding without regex backtracking and preserves legacy truncation semantics on representative + adversarial long inputs. (tests: `test/null-terminated-utf8.test.ts`, `test/archive.test.ts`, `test/tar-xz.test.ts`)
+44. XZ fixture expectations avoid committed ELF binary outputs by pinning deterministic digest/size assertions for BCJ payload verification. (tests: `test/xz-utils-conformance.test.ts`, `test/xz-thirdparty.test.ts`)
+45. Web adapter URL full-fetch overflow paths are fail-fast and bounded: `maxInputBytes` over-limit responses reject with `RangeError`, cancel slow response streams before full transfer, and never use HTTP Range requests. (tests: `test/web-adapter.test.ts`)
+46. Browser smoke verifies web entrypoint behavior in real Chromium/Firefox/WebKit: Blob ZIP roundtrip, ZIP/TAR writer roundtrip, and URL `maxInputBytes` abort remains bounded without HTTP Range requests. (tests: `test/browser/web-entrypoint.pw.ts`)
+47. Security-sensitive + third-party fixture bytes are pinned in `test/fixtures/security-fixture-hashes.json`; `npm run check` fails on missing, unexpected, or changed hashes with explicit diff output. (tests: `test/fixture-hash-manifest.test.ts`, command: `npm run fixtures:hashes:check`)
+48. `npm run format:check` ignores Playwright artifact directories (`test-results/`, `playwright-report/`) so browser smoke artifacts cannot cause false formatting failures in `npm run check`. (tests: `test/format-script.test.ts`)
+49. Web adapter URL inputs reject non-HTTPS schemes (including `http:`) with typed `ARCHIVE_UNSUPPORTED_FEATURE` before any fetch attempt. (tests: `test/security-audit-simulation.test.ts`)
+50. Zip64 boundary parsing is deterministic around 32-bit/64-bit limits: EOCD sentinel combinations requiring Zip64 must provide valid locator/record structures, malformed Zip64 extra fields reject with typed `ZIP_BAD_ZIP64`, and >4GiB central-directory offsets are never truncated to 32-bit values. (tests: `test/zip64-boundary.test.ts`)
+51. Deterministic property tests harden parser boundaries: TAR octal/NUL/space numeric fields, ZIP EOCD comment-length mutations, gzip optional header sections, and web URL `maxInputBytes` abort paths are fuzzed with fixed seeds and bounded runs. (tests: `test/fuzz-property-boundaries.test.ts`)
+52. Unicode Trojan Source directionality controls are blocked by repository scanning: tracked text files must not contain bidi override/isolation control code points, and violations fail `npm run check` with file/line/codepoint diagnostics. (tests: `test/unicode-safety-check.test.ts`)
+53. ZIP writer forced-ZIP64 mode is structurally explicit and typed on corruption: emitted archives include ZIP64 EOCD + locator + ZIP64 central-directory extra fields even for small payloads, remain readable by the ZIP reader, and malformed ZIP64 locator paths reject with typed `ZIP_BAD_ZIP64` (never untyped `RangeError`). (tests: `test/zip64-writer-structural.test.ts`)
+54. Changelog release-truth guard is deterministic: `## Unreleased` must cover core post-release themes (web URL hardening, security simulation corpus, browser smoke scope, zip64 proofs, fixture-hash enforcement, property tests, unicode guard), and missing themes fail `npm run check`. (tests: `test/changelog-unreleased-coverage.test.ts`)
+
+## Gzip support details
+- Header CRC (FHCRC) is validated per RFC 1952 (`https://www.rfc-editor.org/rfc/rfc1952`). (tests: `test/gzip-fhcrc.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+
+## XZ support details
+- Checks supported: none (0x00), CRC32 (0x01), CRC64 (0x04), SHA-256 (0x0A). (tests: `test/xz-utils-conformance.test.ts`, `test/xz-bcj-filters.test.ts`, `test/xz-thirdparty.test.ts`)
+- Filters supported: LZMA2 (0x21), Delta (0x03), BCJ x86 (0x04), PowerPC (0x05), IA64 (0x06), ARM (0x07), ARM-Thumb (0x08), SPARC (0x09), ARM64 (0x0A), RISC-V (0x0B). (tests: `test/xz-utils-conformance.test.ts`, `test/xz-bcj-filters.test.ts`, `test/xz-thirdparty.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- BCJ filter properties are size 0 or 4 bytes with alignment enforced; BCJ filters cannot be last. (tests: `test/xz-bcj-filters.test.ts`)
+- Mixed chains (Delta -> BCJ -> LZMA2) are supported; non-LZMA2 filters apply in reverse order during decode. (tests: `test/xz-mixed-filters.test.ts`)
+- BCJ start offsets are interpreted per stream (reset at concatenation) and applied as provided in filter properties. (tests: `test/xz-bcj-filters.test.ts`, `test/xz-concat-bcj.test.ts`)
+
+## XZ Filter IDs — Sources of Truth
+- Filter IDs 0x04..0x09 are grounded in `specs/xz-file-format.txt` (Filter IDs table).
+- Filter IDs 0x0A (ARM64) and 0x0B (RISC-V) are grounded in `specs/xz-filter-ids.md`.
+
+## Support matrix (format × operation × runtime)
+Legend: ✅ supported · ❌ unsupported (error code in cell) · ⚠️ explicit hint required · 🟦 capability-gated (throws `COMPRESSION_UNSUPPORTED_ALGORITHM` when missing).
+
+### Node (>=24)
+| Format | Detect | List | Audit | Extract | Normalize | Write |
+| --- | --- | --- | --- | --- | --- | --- |
+| zip | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| tar | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| tgz / tar.gz | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| gz | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ✅ |
+| tar.bz2 | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| bz2 | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| tar.xz | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| xz | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| tar.zst | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| zst | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ✅ |
+| tar.br | ⚠️ (format: `tar.br` or filename) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| br | ⚠️ (format: `br` or filename) | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ✅ |
+
+### Deno
+| Format | Detect | List | Audit | Extract | Normalize | Write |
+| --- | --- | --- | --- | --- | --- | --- |
+| zip | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| tar | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| tgz / tar.gz | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| gz | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ✅ |
+| tar.bz2 | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| bz2 | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| tar.xz | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| xz | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| tar.zst | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) |
+| zst | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) |
+| tar.br | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) |
+| br | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) | ❌ (`COMPRESSION_UNSUPPORTED_ALGORITHM`) |
+
+### Bun
+| Format | Detect | List | Audit | Extract | Normalize | Write |
+| --- | --- | --- | --- | --- | --- | --- |
+| zip | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| tar | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| tgz / tar.gz | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| gz | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ✅ |
+| tar.bz2 | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| bz2 | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| tar.xz | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| xz | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| tar.zst | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| zst | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ✅ |
+| tar.br | ⚠️ (format: `tar.br` or filename) | ✅ | ✅ | ✅ | ✅ | ✅ |
+| br | ⚠️ (format: `br` or filename) | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ✅ |
+
+### Web (Browser)
+| Format | Detect | List | Audit | Extract | Normalize | Write |
+| --- | --- | --- | --- | --- | --- | --- |
+| zip | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| tar | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| tgz / tar.gz | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
+| gz | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ✅ |
+| tar.bz2 | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| bz2 | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| tar.xz | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| xz | ✅ | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | ❌ (`ARCHIVE_UNSUPPORTED_FORMAT`) |
+| tar.zst | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 | 🟦 |
+| zst | 🟦 | 🟦 | 🟦 | 🟦 | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | 🟦 |
+| tar.br | ⚠️ (format: `tar.br` or filename; 🟦 on runtimes without brotli streams) | ✅ | ✅ | ✅ | ✅ | 🟦 |
+| br | ⚠️ (format: `br` or filename; 🟦 on runtimes without brotli streams) | ✅ | ✅ | ✅ | ❌ (`ARCHIVE_UNSUPPORTED_FEATURE`) | 🟦 |
+
+Matrix proofs: `test/archive.test.ts`, `test/bun.smoke.ts`, `test/deno.smoke.ts`, `test/xz.test.ts`, `test/bzip2.test.ts`, `test/tar-xz.test.ts`, `test/single-file-formats.test.ts`, `test/archive-writer-proof.test.ts`, `test/audit-normalize-proof.test.ts`, `test/support-matrix-behavior.test.ts`, `test/support-matrix.test.ts`, `test/web-adapter.test.ts`, `test/web-writer-roundtrip.test.ts`.
+Write proofs: `test/archive-writer-proof.test.ts`, `test/archive.test.ts`, `test/bun.smoke.ts`, `test/deno.smoke.ts`, `test/web-writer-roundtrip.test.ts`.
+Write-negative proofs: `test/archive-writer-proof.test.ts`, `test/deno.smoke.ts`.
+
+```json support-matrix
+{
+  "formats": [
+    "zip",
+    "tar",
+    "tgz",
+    "tar.gz",
+    "gz",
+    "bz2",
+    "tar.bz2",
+    "zst",
+    "tar.zst",
+    "br",
+    "tar.br",
+    "xz",
+    "tar.xz"
+  ],
+  "operations": ["detect", "list", "audit", "extract", "normalize", "write"],
+  "runtimes": ["node", "deno", "bun", "web"]
+}
+```
+
+## Web runtime notes
+- Entry point: `@ismail-elkorchi/bytefold/web` / `./web`.
+- Supported input kinds in the web adapter: `Uint8Array`, `ArrayBuffer`, `ReadableStream<Uint8Array>`, `Blob`/`File`, and HTTPS URL.
+- URL behavior in web adapter: only HTTPS URLs are accepted; responses are always full-fetched before archive detection/opening, and no seekable HTTP range session is attempted in web adapter by design. `maxInputBytes` is enforced both from `Content-Length` and during streaming reads, with over-limit chunked/slow responses canceled before full transfer. (tests: `test/web-adapter.test.ts`, `test/security-audit-simulation.test.ts`)
+- ZIP on Blob uses seekable random access (`blob.slice(start, end).arrayBuffer()`), so listing/extracting ZIP from Blob stays bounded by seek budget and avoids full Blob buffering. (tests: `test/web-adapter.test.ts`)
+- Web write roundtrip contract: ZIP (store-only mode) and TAR can be created through the web entrypoint into pure Web `WritableStream` sinks, wrapped in Blob, and reopened with matching entry names/bytes plus safe audit/normalize behavior. (tests: `test/web-writer-roundtrip.test.ts`)
+- Browser credibility contract: Chromium smoke executes the web entrypoint in a real browser and proves Blob ZIP roundtrip, ZIP/TAR writer roundtrip, and URL `maxInputBytes` adversarial abort behavior (bounded transfer + no `Range` requests). (tests: `test/browser/web-entrypoint.pw.ts`)
+- XZ seekable preflight over Blob is not implemented in this iteration; Blob XZ paths use bounded full-buffer input handling and existing decode-time resource ceilings. (tests: `test/web-adapter.test.ts`, `test/resource-ceilings.test.ts`)
+- Compression capability reporting for web runtime:
+  - `getCompressionCapabilities()` probes `CompressionStream` and `DecompressionStream` constructor acceptance independently for algorithm strings `gzip`, `deflate`, `deflate-raw`, `brotli`, and `zstd`;
+  - each algorithm reports `compress` and `decompress` truthfully per constructor acceptance; unsupported modes surface `COMPRESSION_UNSUPPORTED_ALGORITHM` when requested;
+  - pure-JS decode support remains for `bzip2` and `xz`;
+  - when either web compression constructor is missing, `notes` includes an explicit missing-constructor message. (tests: `test/compress-runtime-web.test.ts`, `test/support-matrix-behavior.test.ts`, `test/schema-contracts.test.ts`)
+- Runtime detection for capabilities uses `runtime: "web"` when Bun/Deno/Node markers are absent and either web compression global exists (`CompressionStream` or `DecompressionStream`). (tests: `test/compress-runtime-web.test.ts`, `test/schema-contracts.test.ts`)
+
+## Single-file compressed formats: entry naming
+Naming is deterministic and sanitized to a single path segment. (tests: `test/single-file-formats.test.ts`)
+- Inputs with a filename hint (file path or URL): use the final path segment, strip the compression extension, and return `name` or `name.tar` for `.tar.*` variants.
+- Inputs without a filename hint (bytes/streams): default to `data`, except gzip may use a header FNAME if present.
+- Gzip header options: FEXTRA and FCOMMENT fields are skipped per RFC1952 and do not block FNAME parsing. (tests: `test/gzip-header-options.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- Gzip FNAME: used only after sanitization (basename only; NUL, empty, `.`/`..` rejected). If rejected or missing, fall back to filename or `data`.
+
+## Normalization determinism
+- Deterministic normalization (`isDeterministic: true`) emits stable bytes for zip and tar; normalizing an already normalized archive yields byte-identical output. (tests: `test/audit-normalize-proof.test.ts`)
+- For tar-wrapped compressed formats, normalization produces a deterministic tar stream and preserves entry names + contents. (tests: `test/audit-normalize-proof.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+
+## Ambiguity policy (normalize safe mode)
+- Collision key pipeline: path normalization (slashes + dot segments) → `normalize('NFC')` → full Unicode case folding (from `specs/unicode/CaseFolding-17.0.0.txt`, statuses C+F, T excluded) → `normalize('NFC')`. (tests: `test/unicode-collision.test.ts`, `test/casefold-collision.test.ts`)
+- Duplicate paths: error (tar → `ARCHIVE_NAME_COLLISION` + `TAR_DUPLICATE_ENTRY`, zip → `ZIP_NAME_COLLISION` + `ZIP_DUPLICATE_ENTRY`). (tests: `test/ambiguous-fixtures.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- Case-fold collisions: error (tar → `ARCHIVE_NAME_COLLISION` + `TAR_CASE_COLLISION`, zip → `ZIP_NAME_COLLISION` + `ZIP_CASE_COLLISION`). (tests: `test/ambiguous-fixtures.test.ts`, `test/casefold-collision.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- Unicode normalization collisions (NFC): error (tar → `ARCHIVE_NAME_COLLISION` + `TAR_UNICODE_COLLISION`, zip → `ZIP_NAME_COLLISION` + `ZIP_UNICODE_COLLISION`). (tests: `test/unicode-collision.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- Directory/file kind conflict (`dir` vs `dir/`): allowed; entries remain distinct after normalization. (tests: `test/ambiguous-fixtures.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- Symlinks: rejected in normalize safe mode (tar → `ARCHIVE_UNSUPPORTED_FEATURE` + `TAR_SYMLINK_PRESENT`, zip → `ZIP_SYMLINK_DISALLOWED`). (tests: `test/ambiguous-fixtures.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`, `test/error-contracts.test.ts`)
+- Hardlinks (tar `link` entries): rejected in normalize safe mode (`ARCHIVE_UNSUPPORTED_FEATURE` + `TAR_UNSUPPORTED_ENTRY`). (tests: `test/ambiguous-fixtures.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- Path normalization: backslashes are normalized to `/`, `.` segments and repeated slashes are removed; absolute paths, drive-letter prefixes, and `..` segments are rejected with path traversal errors. (tests: `test/ambiguous-fixtures.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+
+## Security model (name collisions)
+- Unicode normalization collisions are rejected in audit/normalize/extract because filesystem normalization differs across platforms, and accepting them can cause nondeterministic overwrites. (tests: `test/unicode-collision.test.ts`)
+
+## Concatenation semantics (gzip, bzip2)
+- Gzip concatenated members decode sequentially across Node, Deno, and Bun. (tests: `test/single-file-formats.test.ts`, `test/bun.smoke.ts`, `test/deno.smoke.ts`)
+- Bzip2 concatenated streams decode sequentially across runtimes. (tests: `test/single-file-formats.test.ts`, `test/bun.smoke.ts`, `test/deno.smoke.ts`)
+
+## Resource ceilings
+- Defaults (single source: `src/limits.ts`): `maxXzDictionaryBytes = 64 MiB` (agent profile: 32 MiB), `maxXzBufferedBytes = 1 MiB`, `maxXzIndexRecords = 1,000,000` (agent profile: 200,000), `maxXzIndexBytes = 64 MiB` (agent profile: 16 MiB), `maxXzPreflightBlockHeaders = 1024` (agent profile: 256), `maxZipCentralDirectoryBytes = 64 MiB` (agent profile: 16 MiB), `maxZipCommentBytes = 65,535` (agent profile: 16,384), `maxZipEocdSearchBytes = 65,558`, `maxBzip2BlockSize = 9`. (tests: `test/resource-ceilings.test.ts`, `test/resource-defaults.test.ts`, `test/xz-index-limits.test.ts`, `test/xz-seekable-preflight.test.ts`, `test/zip-seekable-preflight.test.ts`)
+- `maxXzPreflightBlockHeaders` bounds seekable dictionary preflight; `0` disables block-header scanning and yields `COMPRESSION_RESOURCE_PREFLIGHT_INCOMPLETE` (info). (tests: `test/xz-seekable-preflight.test.ts`)
+- Rationale: XZ Index fields are encoded as VLIs up to 63 bits (`specs/xz-file-format.txt`), so record counts and index sizes can be arbitrarily large; the defaults cap scan time/space while allowing typical archives. (tests: `test/xz-index-limits.test.ts`)
+- XZ Index VLI decoding is streaming-safe even when VLI bytes split across chunks. (tests: `test/xz-vli-boundaries.test.ts`)
+- Overrides: ceilings are configurable via `limits` in `openArchive(...)`, `ArchiveReader.audit(...)`, and `ArchiveReader.normalizeToWritable(...)`, and via `limits` in `createDecompressor(...)`. (tests: `test/resource-ceilings.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- Precedence rules (profile vs limits):
+  - `openArchive(...)`: `profile` chooses reader defaults (`strict` mode + default limits), then `limits` overrides only the specified fields; unspecified fields stay on profile defaults. (tests: `test/option-precedence.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+  - `ZipReader` / `TarReader` construction: same rule as `openArchive` because the constructors resolve `profile` defaults first, then merge explicit `limits` field-by-field, and `isStrict` (if set) overrides profile strictness. (tests: `test/option-precedence.test.ts`)
+  - `createDecompressor(...)`: explicit scalar knobs (`maxOutputBytes`, `maxCompressionRatio`, `maxDictionaryBytes`, `maxBufferedInputBytes`) take precedence over their `limits` counterparts; remaining values come from `limits`; `profile` still controls behavior independently (for example, unsupported XZ checks in strict vs compat). (tests: `test/option-precedence.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`, `test/xz-utils-conformance.test.ts`)
+  - `createArchiveWriter(...)`: no `profile`/`limits` API exists for writer creation; precedence is not applicable. (tests: `test/archive.test.ts`, `test/archive-writer-proof.test.ts`)
+- Audit preflight: bzip2 block size and xz dictionary size are checked from headers and reported as `COMPRESSION_RESOURCE_LIMIT` without full decompression. (tests: `test/resource-ceilings.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`, `test/xz-seekable-preflight.test.ts`)
+- `maxTotalDecompressedBytes` enforces output ceilings for gzip/deflate/brotli/zstd with `COMPRESSION_RESOURCE_LIMIT` and no output beyond the limit. (tests: `test/compression-resource-limits.test.ts`)
+
+## Concatenation and resource ceilings
+- XZ: preflight scans concatenated streams using stream headers + Index records (no payload decompression), applies Index ceilings across the concatenation, and scans Block Headers to enforce dictionary limits up to `maxXzPreflightBlockHeaders` per stream. If block count exceeds the limit, audit emits `COMPRESSION_RESOURCE_PREFLIGHT_INCOMPLETE` (info) with `requiredBlockHeaders` + `limitBlockHeaders`, and dictionary limits remain enforced during decode. (tests: `test/resource-ceilings.test.ts`, `test/xz-index-limits.test.ts`, `test/xz-seekable-preflight.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- XZ preflight scanning is O(1) memory with respect to Index record count (no per-record arrays). (tests: `test/xz-index-limits.test.ts`)
+- Bzip2: preflight only inspects the first member; audit emits `COMPRESSION_RESOURCE_PREFLIGHT_INCOMPLETE` when bzip2 limits are in effect, and concatenated members are enforced during decode. (tests: `test/resource-ceilings.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- Seekable XZ preflight: for file paths or HTTP Range URLs, index + dictionary limits run before full buffering; HTTP failures map to `ARCHIVE_HTTP_*` codes with preserved `context.httpCode`. (tests: `test/xz-http-error-mapping.test.ts`, `test/xz-seekable-preflight.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- Seekable ZIP preflight: for file paths or HTTP Range URLs, EOCD/central-directory limits run before full buffering; Range is required for HTTP preflight; multi-disk archives are rejected. (tests: `test/zip-seekable-preflight.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+- HTTP Range random access: validators (ETag/Last-Modified) are pinned, `If-Range` is used only with strong ETags, header-only failures abort before body consumption, content codings are rejected, and 206 body length must exactly match the requested range. (specs: `specs/http/rfc9110-if-range.md`, `specs/http/rfc9110-accept-encoding.md`; tests: `test/zip-url-seekable-budget.test.ts`, `test/deno.smoke.ts`, `test/bun.smoke.ts`)
+
+## Error model
+- Stable error classes: `ZipError`, `CompressionError`, `ArchiveError`.
+- Stable error codes are defined in `src/errors.ts`, `src/compress/errors.ts`, and `src/archive/errors.ts`.
+- Error JSON includes `schemaVersion: "1"` plus `hint` and `context`, and serializes as plain objects with string/number fields only.
+- Error JSON context policy: `context` MUST NOT duplicate any top-level key name. Keys that are top-level in an error payload (`schemaVersion`, `name`, `code`, `message`, `hint`, `context`, plus optional top-level fields like `entryName`, `method`, `offset`, `algorithm`) are stripped from `context` during serialization so machine consumers have one canonical location per fact. (tests: `test/error-json-ambiguity.test.ts`, `test/error-contracts.test.ts`)
+- JSON schema: `schemas/error.schema.json`. (tests: `test/schema-contracts.test.ts`, `test/error-contracts.test.ts`)
+
+## Report model
+- Reports are JSON-safe objects with `schemaVersion: "1"` and primitive fields only.
+- `ArchiveDetectionReport`, `ArchiveAuditReport`, `ArchiveNormalizeReport`, and `CompressionCapabilities` use numbers/strings/arrays only; no `bigint`.
+- Any report `toJSON()` implementation MUST return JSON-safe data.
+- JSON schemas: `schemas/detection-report.schema.json`, `schemas/audit-report.schema.json`, `schemas/normalize-report.schema.json`, `schemas/capabilities-report.schema.json`. (tests: `test/schema-contracts.test.ts`)
+
+## Schema validation
+Supported JSON Schema subset (enforced by `test/schema-contracts.test.ts` and `test/schema-validator.ts`): `type`, `required`, `properties`, `enum`, `items`, `additionalProperties`.

package/dist/abort.d.ts

@@ -0,0 +1,3 @@
+export declare function throwIfAborted(signal?: AbortSignal | null): void;
+export declare function mergeSignals(...signals: Array<AbortSignal | null | undefined>): AbortSignal | undefined;
+//# sourceMappingURL=abort.d.ts.map

package/dist/abort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.d.ts","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAQhE;AAED,wBAAgB,YAAY,CAAC,GAAG,OAAO,EAAE,KAAK,CAAC,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC,GAAG,WAAW,GAAG,SAAS,CAsBvG"}

package/dist/abort.js

@@ -0,0 +1,33 @@
+export function throwIfAborted(signal) {
+    if (!signal)
+        return;
+    if (!signal.aborted)
+        return;
+    const reason = signal.reason;
+    if (reason instanceof Error) {
+        throw reason;
+    }
+    throw reason ?? new DOMException('The operation was aborted', 'AbortError');
+}
+export function mergeSignals(...signals) {
+    const active = signals.filter((signal) => !!signal);
+    if (active.length === 0)
+        return undefined;
+    if (active.length === 1)
+        return active[0];
+    if (typeof AbortSignal.any === 'function') {
+        return AbortSignal.any(active);
+    }
+    const controller = new AbortController();
+    for (const signal of active) {
+        if (signal.aborted) {
+            controller.abort(signal.reason);
+            break;
+        }
+        signal.addEventListener('abort', () => {
+            controller.abort(signal.reason);
+        }, { once: true });
+    }
+    return controller.signal;
+}
+//# sourceMappingURL=abort.js.map

package/dist/abort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"abort.js","sourceRoot":"","sources":["../src/abort.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,cAAc,CAAC,MAA2B;IACxD,IAAI,CAAC,MAAM;QAAE,OAAO;IACpB,IAAI,CAAC,MAAM,CAAC,OAAO;QAAE,OAAO;IAC5B,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC7B,IAAI,MAAM,YAAY,KAAK,EAAE,CAAC;QAC5B,MAAM,MAAM,CAAC;IACf,CAAC;IACD,MAAM,MAAM,IAAI,IAAI,YAAY,CAAC,2BAA2B,EAAE,YAAY,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAG,OAA8C;IAC5E,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,MAAM,EAAyB,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAC3E,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IAC1C,IAAI,OAAO,WAAW,CAAC,GAAG,KAAK,UAAU,EAAE,CAAC;QAC1C,OAAO,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,KAAK,MAAM,MAAM,IAAI,MAAM,EAAE,CAAC;QAC5B,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YAChC,MAAM;QACR,CAAC;QACD,MAAM,CAAC,gBAAgB,CACrB,OAAO,EACP,GAAG,EAAE;YACH,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAC;IACJ,CAAC;IACD,OAAO,UAAU,CAAC,MAAM,CAAC;AAC3B,CAAC"}

package/dist/archive/errors.d.ts

@@ -0,0 +1,34 @@
+/** Stable archive error codes. */
+export type ArchiveErrorCode = 'ARCHIVE_UNSUPPORTED_FORMAT' | 'ARCHIVE_TRUNCATED' | 'ARCHIVE_BAD_HEADER' | 'ARCHIVE_NAME_COLLISION' | 'ARCHIVE_PATH_TRAVERSAL' | 'ARCHIVE_LIMIT_EXCEEDED' | 'ARCHIVE_UNSUPPORTED_FEATURE' | 'ARCHIVE_HTTP_RANGE_UNSUPPORTED' | 'ARCHIVE_HTTP_RANGE_INVALID' | 'ARCHIVE_HTTP_RESOURCE_CHANGED' | 'ARCHIVE_HTTP_CONTENT_ENCODING' | 'ARCHIVE_HTTP_STRONG_ETAG_REQUIRED' | 'ARCHIVE_HTTP_BAD_RESPONSE' | 'ARCHIVE_HTTP_SIZE_UNKNOWN' | 'ARCHIVE_AUDIT_FAILED';
+/** Error thrown for archive-level failures and safety violations. */
+export declare class ArchiveError extends Error {
+    /** Machine-readable error code. */
+    readonly code: ArchiveErrorCode;
+    /** Entry name related to the error, if available. */
+    readonly entryName?: string | undefined;
+    /** Offset (in bytes) related to the error, if available. */
+    readonly offset?: bigint | undefined;
+    /** Underlying cause, if available. */
+    readonly cause?: unknown;
+    /** Additional context for serialization. */
+    readonly context?: Record<string, string> | undefined;
+    /** Create an ArchiveError with a stable code. */
+    constructor(code: ArchiveErrorCode, message: string, options?: {
+        entryName?: string | undefined;
+        offset?: bigint | undefined;
+        context?: Record<string, string> | undefined;
+        cause?: unknown;
+    });
+    /** JSON-safe serialization with schemaVersion "1". */
+    toJSON(): {
+        schemaVersion: string;
+        name: string;
+        code: ArchiveErrorCode;
+        message: string;
+        hint: string;
+        context: Record<string, string>;
+        entryName?: string;
+        offset?: string;
+    };
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/archive/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/archive/errors.ts"],"names":[],"mappings":"AAGA,kCAAkC;AAClC,MAAM,MAAM,gBAAgB,GACxB,4BAA4B,GAC5B,mBAAmB,GACnB,oBAAoB,GACpB,wBAAwB,GACxB,wBAAwB,GACxB,wBAAwB,GACxB,6BAA6B,GAC7B,gCAAgC,GAChC,4BAA4B,GAC5B,+BAA+B,GAC/B,+BAA+B,GAC/B,mCAAmC,GACnC,2BAA2B,GAC3B,2BAA2B,GAC3B,sBAAsB,CAAC;AAE3B,qEAAqE;AACrE,qBAAa,YAAa,SAAQ,KAAK;IACrC,mCAAmC;IACnC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,qDAAqD;IACrD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,sCAAsC;IACtC,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;IAClC,4CAA4C;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAEtD,iDAAiD;gBAE/C,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC/B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QAC5B,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;QAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;IAWH,sDAAsD;IACtD,MAAM,IAAI;QACR,aAAa,EAAE,MAAM,CAAC;QACtB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,gBAAgB,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAChC,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB;CAgBF"}

package/dist/archive/errors.js

@@ -0,0 +1,45 @@
+import { sanitizeErrorContext } from '../errorContext.js';
+import { BYTEFOLD_REPORT_SCHEMA_VERSION } from '../reportSchema.js';
+/** Error thrown for archive-level failures and safety violations. */
+export class ArchiveError extends Error {
+    /** Machine-readable error code. */
+    code;
+    /** Entry name related to the error, if available. */
+    entryName;
+    /** Offset (in bytes) related to the error, if available. */
+    offset;
+    /** Underlying cause, if available. */
+    cause;
+    /** Additional context for serialization. */
+    context;
+    /** Create an ArchiveError with a stable code. */
+    constructor(code, message, options) {
+        super(message, options?.cause ? { cause: options.cause } : undefined);
+        this.name = 'ArchiveError';
+        this.code = code;
+        this.entryName = options?.entryName;
+        this.offset = options?.offset;
+        this.context = options?.context;
+        this.cause = options?.cause;
+    }
+    /** JSON-safe serialization with schemaVersion "1". */
+    toJSON() {
+        const topLevelShadowKeys = [];
+        if (this.entryName !== undefined)
+            topLevelShadowKeys.push('entryName');
+        if (this.offset !== undefined)
+            topLevelShadowKeys.push('offset');
+        const context = sanitizeErrorContext(this.context, topLevelShadowKeys);
+        return {
+            schemaVersion: BYTEFOLD_REPORT_SCHEMA_VERSION,
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            hint: this.message,
+            context,
+            ...(this.entryName !== undefined ? { entryName: this.entryName } : {}),
+            ...(this.offset !== undefined ? { offset: this.offset.toString() } : {})
+        };
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/archive/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/archive/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAoBpE,qEAAqE;AACrE,MAAM,OAAO,YAAa,SAAQ,KAAK;IACrC,mCAAmC;IAC1B,IAAI,CAAmB;IAChC,qDAAqD;IAC5C,SAAS,CAAsB;IACxC,4DAA4D;IACnD,MAAM,CAAsB;IACrC,sCAAsC;IACpB,KAAK,CAAW;IAClC,4CAA4C;IACnC,OAAO,CAAsC;IAEtD,iDAAiD;IACjD,YACE,IAAsB,EACtB,OAAe,EACf,OAKC;QAED,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,OAAO,EAAE,SAAS,CAAC;QACpC,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;QAC9B,IAAI,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;QAChC,IAAI,CAAC,KAAK,GAAG,OAAO,EAAE,KAAK,CAAC;IAC9B,CAAC;IAED,sDAAsD;IACtD,MAAM;QAUJ,MAAM,kBAAkB,GAAa,EAAE,CAAC;QACxC,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,kBAAkB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACvE,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS;YAAE,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACjE,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;QACvE,OAAO;YACL,aAAa,EAAE,8BAA8B;YAC7C,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,IAAI,EAAE,IAAI,CAAC,OAAO;YAClB,OAAO;YACP,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACtE,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzE,CAAC;IACJ,CAAC;CACF"}

package/dist/archive/httpArchiveErrors.d.ts

@@ -0,0 +1,2 @@
+export declare function mapHttpErrorToArchiveError(err: unknown, context?: Record<string, string>): unknown;
+//# sourceMappingURL=httpArchiveErrors.d.ts.map

package/dist/archive/httpArchiveErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpArchiveErrors.d.ts","sourceRoot":"","sources":["../../src/archive/httpArchiveErrors.ts"],"names":[],"mappings":"AAaA,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAWlG"}

package/dist/archive/httpArchiveErrors.js

@@ -0,0 +1,25 @@
+import { HttpError } from '../http/errors.js';
+import { ArchiveError } from './errors.js';
+const HTTP_ERROR_TO_ARCHIVE_ERROR = {
+    HTTP_RANGE_UNSUPPORTED: 'ARCHIVE_HTTP_RANGE_UNSUPPORTED',
+    HTTP_RANGE_INVALID: 'ARCHIVE_HTTP_RANGE_INVALID',
+    HTTP_RESOURCE_CHANGED: 'ARCHIVE_HTTP_RESOURCE_CHANGED',
+    HTTP_CONTENT_ENCODING: 'ARCHIVE_HTTP_CONTENT_ENCODING',
+    HTTP_STRONG_ETAG_REQUIRED: 'ARCHIVE_HTTP_STRONG_ETAG_REQUIRED',
+    HTTP_BAD_RESPONSE: 'ARCHIVE_HTTP_BAD_RESPONSE',
+    HTTP_SIZE_UNKNOWN: 'ARCHIVE_HTTP_SIZE_UNKNOWN'
+};
+export function mapHttpErrorToArchiveError(err, context) {
+    if (!(err instanceof HttpError))
+        return err;
+    const mappedCode = HTTP_ERROR_TO_ARCHIVE_ERROR[err.code] ?? 'ARCHIVE_HTTP_BAD_RESPONSE';
+    return new ArchiveError(mappedCode, err.message, {
+        context: {
+            ...(context ?? {}),
+            ...(err.context ?? {}),
+            httpCode: err.code
+        },
+        cause: err
+    });
+}
+//# sourceMappingURL=httpArchiveErrors.js.map

package/dist/archive/httpArchiveErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"httpArchiveErrors.js","sourceRoot":"","sources":["../../src/archive/httpArchiveErrors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAsB,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,YAAY,EAAyB,MAAM,aAAa,CAAC;AAElE,MAAM,2BAA2B,GAA4C;IAC3E,sBAAsB,EAAE,gCAAgC;IACxD,kBAAkB,EAAE,4BAA4B;IAChD,qBAAqB,EAAE,+BAA+B;IACtD,qBAAqB,EAAE,+BAA+B;IACtD,yBAAyB,EAAE,mCAAmC;IAC9D,iBAAiB,EAAE,2BAA2B;IAC9C,iBAAiB,EAAE,2BAA2B;CAC/C,CAAC;AAEF,MAAM,UAAU,0BAA0B,CAAC,GAAY,EAAE,OAAgC;IACvF,IAAI,CAAC,CAAC,GAAG,YAAY,SAAS,CAAC;QAAE,OAAO,GAAG,CAAC;IAC5C,MAAM,UAAU,GAAG,2BAA2B,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,2BAA2B,CAAC;IACxF,OAAO,IAAI,YAAY,CAAC,UAAU,EAAE,GAAG,CAAC,OAAO,EAAE;QAC/C,OAAO,EAAE;YACP,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;YAClB,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;YACtB,QAAQ,EAAE,GAAG,CAAC,IAAI;SACnB;QACD,KAAK,EAAE,GAAG;KACX,CAAC,CAAC;AACL,CAAC"}

package/dist/archive/index.d.ts

@@ -0,0 +1,47 @@
+import type { ArchiveAuditReport, ArchiveDetectionReport, ArchiveEntry, ArchiveFormat, ArchiveLimits, ArchiveNormalizeReport, ArchiveOpenOptions, ArchiveProfile } from './types.js';
+import type { ZipWriterOptions } from '../types.js';
+import type { TarWriterOptions } from '../tar/types.js';
+/** Unified archive reader API returned by openArchive(). */
+export type ArchiveReader = {
+    format: ArchiveFormat;
+    detection?: ArchiveDetectionReport;
+    entries(): AsyncGenerator<ArchiveEntry>;
+    audit(options?: ArchiveAuditOptions): Promise<ArchiveAuditReport>;
+    assertSafe(options?: ArchiveAuditOptions): Promise<void>;
+    normalizeToWritable?(writable: WritableStream<Uint8Array>, options?: ArchiveNormalizeOptions): Promise<ArchiveNormalizeReport>;
+};
+/** Unified archive writer API for ZIP/TAR and layered formats. */
+export type ArchiveWriter = {
+    format: ArchiveFormat;
+    add(name: string, source?: Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>, options?: unknown): Promise<void>;
+    close(): Promise<void>;
+};
+/** Options for creating archive writers. */
+export type ArchiveWriterOptions = {
+    zip?: ZipWriterOptions;
+    tar?: TarWriterOptions;
+    compression?: {
+        level?: number;
+        quality?: number;
+    };
+};
+/** Options for auditing archives opened via openArchive(). */
+export type ArchiveAuditOptions = {
+    profile?: ArchiveProfile;
+    isStrict?: boolean;
+    limits?: ArchiveLimits;
+    signal?: AbortSignal;
+};
+/** Options for normalization via openArchive(). */
+export type ArchiveNormalizeOptions = {
+    isDeterministic?: boolean;
+    limits?: ArchiveLimits;
+    signal?: AbortSignal;
+};
+/** Inputs accepted by openArchive(). */
+export type ArchiveInput = Uint8Array | ArrayBuffer | ReadableStream<Uint8Array> | Blob;
+/** Open an archive with auto-detection (or a forced format). */
+export declare function openArchive(input: ArchiveInput, options?: ArchiveOpenOptions): Promise<ArchiveReader>;
+/** Create an archive writer for a specific format. */
+export declare function createArchiveWriter(format: ArchiveFormat, writable: WritableStream<Uint8Array>, options?: ArchiveWriterOptions): ArchiveWriter;
+//# sourceMappingURL=index.d.ts.map

package/dist/archive/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/archive/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,EACZ,aAAa,EAGb,aAAa,EACb,sBAAsB,EACtB,kBAAkB,EAClB,cAAc,EACf,MAAM,YAAY,CAAC;AAcpB,OAAO,KAAK,EAKV,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,KAAK,EAA0D,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAOhH,4DAA4D;AAC5D,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,CAAC,EAAE,sBAAsB,CAAC;IACnC,OAAO,IAAI,cAAc,CAAC,YAAY,CAAC,CAAC;IACxC,KAAK,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAClE,UAAU,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzD,mBAAmB,CAAC,CAClB,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,EACpC,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,sBAAsB,CAAC,CAAC;CACpC,CAAC;AAEF,kEAAkE;AAClE,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,aAAa,CAAC;IACtB,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,aAAa,CAAC,UAAU,CAAC,EAC1F,OAAO,CAAC,EAAE,OAAO,GAChB,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AAEF,4CAA4C;AAC5C,MAAM,MAAM,oBAAoB,GAAG;IACjC,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,GAAG,CAAC,EAAE,gBAAgB,CAAC;IACvB,WAAW,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACpD,CAAC;AAyBF,8DAA8D;AAC9D,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,mDAAmD;AACnD,MAAM,MAAM,uBAAuB,GAAG;IACpC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,wCAAwC;AACxC,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,WAAW,GAAG,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;AAExF,gEAAgE;AAChE,wBAAsB,WAAW,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAqD3G;AAwFD,sDAAsD;AACtD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,EACpC,OAAO,CAAC,EAAE,oBAAoB,GAC7B,aAAa,CA0Df"}