archive-codec 0.0.0 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joseph Mearman
+
+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,73 @@
+# archive-codec
+
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/archive-codec) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/archive-codec) [![Release](https://img.shields.io/github/v/release/ExaDev/archive-codec)](https://github.com/ExaDev/archive-codec/releases/latest) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/archive-codec/ci.yml?branch=main)](https://github.com/ExaDev/archive-codec/actions)
+
+> Recursive archive (ZIP-in-ZIP) detection and walking with depth and cumulative decompressed-size guards — zero document-format knowledge, the archive utility package for the [documents.js family](https://github.com/ExaDev). Worker-isomorphic: the same code runs under Node and inside a Cloudflare Workers isolate.
+
+Created for [documents.js#564](https://github.com/ExaDev/documents.js/issues/564): nothing in the ecosystem recursed into a nested archive. Most concretely, OOXML's embedded-object model — a docx/pptx carrying a genuinely separate ZIP blob at `word/embeddings/oleObject1.xlsx` — had no safe handling anywhere, and no package guarded against recursive-archive inputs at all (`byte-codec`'s 512 MiB per-stream inflate cap does not compose across recursion). A new sibling was chosen over extending `byte-codec` (whose charter is byte/image primitives, zero container-format knowledge) or doing it inline in `documents.js` (which would repeat the duplication `byte-codec`'s own extraction was meant to avoid). No family package depends on it yet; `documents.js` consuming it for OOXML embedded objects is planned follow-up work.
+
+Scope for v1: **ZIP containers only** — read and write over [`fflate`](https://github.com/101arrowz/fflate), recursive walking of ZIP-in-ZIP entries, and archive-format detection (ZIP vs not-ZIP). **tar and gzip are explicitly out of scope.**
+
+## Getting started
+
+Requires Node.js `>=20` and pnpm `11.6.0`.
+
+```sh
+pnpm install
+pnpm build          # tsdown -> dist/ (ESM + CJS + .d.ts)
+pnpm typecheck      # tsc -p tsconfig.json && tsc -p tsconfig.node.json (dual tsconfig)
+pnpm lint           # eslint . --fix --cache --max-warnings 0
+pnpm test           # vitest run
+pnpm test:watch     # vitest
+pnpm test:workers   # vitest run --config vitest.workers.config.ts, inside a real Cloudflare Workers (workerd) isolate
+```
+
+To run a single test file, pass its path to vitest directly, e.g. `pnpm exec vitest run src/zip/walk.test.ts`.
+
+## What it provides
+
+| Module | Exports |
+|---|---|
+| `zip/container` | `zipPackage` (ordered-entries ZIP write with stored-uncompressed support), `unzipPackage`, `ZipEntry` |
+| `zip/detect` | `detectArchiveFormat` (`'zip' \| 'unknown'`), `isZipArchive`, `ArchiveFormat` |
+| `zip/walk` | `walkArchive` (recursive ZIP-in-ZIP walking), `ArchiveWalkEntry`, `ArchiveWalkLimitError`, `MAX_WALK_DEPTH`, `MAX_WALK_TOTAL_BYTES`, `WalkArchiveOptions` |
+
+### Recursive walking
+
+```ts
+import { walkArchive } from 'archive-codec';
+
+// Every entry of every nested ZIP, flattened. Throws ArchiveWalkLimitError if
+// the walk exceeds the depth cap or the cumulative decompressed-bytes budget.
+for (const entry of walkArchive(docxBytes)) {
+  entry.path;      // e.g. 'xl/workbook.xml', the path within its own archive
+  entry.ancestors; // e.g. ['word/embeddings/oleObject1.xlsx'] -- the nested
+                   // ZIP entries descended through to reach this one
+  entry.bytes;     // decompressed content
+}
+```
+
+Both guards throw rather than truncate: an input outside the contract must fail loudly, never return a partial listing that looks complete. The defaults are `MAX_WALK_DEPTH` (8 — real producers bottom out around depth 3; the motivating OOXML embedded-object case is depth 2) and `MAX_WALK_TOTAL_BYTES` (512 MiB cumulative across every nesting level — the same figure `byte-codec` grants a single stream, re-purposed as one shared budget so a bomb's multiplicative nesting leverage becomes bounded addition). Both are overridable per call via `walkArchive(bytes, { maxDepth, maxTotalBytes })`, and each constant's derivation is stated in its source comment.
+
+### ZIP container
+
+`zipPackage` takes an *ordered* array of `[path, entry]` tuples, not a `Record`, so the caller controls the exact emission order deterministically (the property formats with a fixed-offset first entry — ODF's `mimetype` — depend on), and any entry can be written stored-uncompressed via `stored: true`. `unzipPackage` is the read side; the returned `Record` makes no ordering promise and collapses duplicate paths.
+
+## Conventions
+
+- Worker-isomorphic (see the [family-wide convention](https://github.com/ExaDev/documents.js/blob/main/README.md#conventions)): runtime `src/` must not import `node:*`, a bare Node builtin, or use the `Buffer` global — enforced by a `no-restricted-imports`/`no-restricted-globals` ESLint rule and exercised in CI by running the test suite inside an actual `workerd` isolate (`pnpm test:workers`). Test files under `src/**/*.test.ts` and `src/test-support/` are exempt and may use Node APIs for fixtures.
+- Only `src/index.ts` may be named `index.*` — a custom ESLint rule (`local/no-non-barrel-index`) rejects any other module using an `index` basename, since that would be a hidden entry point the `exports` map in `package.json` doesn't advertise.
+- Zero document-format knowledge: this package knows bytes and ZIP structure, never that any entry is a document. It depends only on `fflate` — not on `byte-codec`, `ooxml.js`, or `odf.js` (whose ZIP wrappers it deliberately mirrors rather than imports, keeping their branding and release cadences decoupled).
+- Releases are fully automated: a push to `main` runs `semantic-release` in CI, which determines the version from Conventional Commit messages and publishes to npm via OIDC trusted publishing (no local `NPM_TOKEN` needed). There is no manual publish step.
+
+## Install
+
+```sh
+pnpm add archive-codec
+# or
+npm install archive-codec
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,80 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let fflate = require("fflate");
+//#region src/zip/container.ts
+function unzipPackage(bytes) {
+	return (0, fflate.unzipSync)(bytes);
+}
+function zipPackage(entries) {
+	const data = {};
+	for (const [path, entry] of entries) if (entry.stored === true) data[path] = [entry.bytes, { level: 0 }];
+	else data[path] = entry.bytes;
+	return (0, fflate.zipSync)(data);
+}
+//#endregion
+//#region src/zip/detect.ts
+const ZIP_LOCAL_FILE_HEADER_MAGIC = [
+	80,
+	75,
+	3,
+	4
+];
+const ZIP_END_OF_CENTRAL_DIRECTORY_MAGIC = [
+	80,
+	75,
+	5,
+	6
+];
+function startsWithMagic(bytes, magic) {
+	if (bytes.length < magic.length) return false;
+	for (let i = 0; i < magic.length; i++) if (bytes[i] !== magic[i]) return false;
+	return true;
+}
+function isZipArchive(bytes) {
+	return startsWithMagic(bytes, ZIP_LOCAL_FILE_HEADER_MAGIC) || startsWithMagic(bytes, ZIP_END_OF_CENTRAL_DIRECTORY_MAGIC);
+}
+function detectArchiveFormat(bytes) {
+	return isZipArchive(bytes) ? "zip" : "unknown";
+}
+//#endregion
+//#region src/zip/walk.ts
+const MAX_WALK_DEPTH = 8;
+const MAX_WALK_TOTAL_BYTES = 536870912;
+var ArchiveWalkLimitError = class extends Error {
+	limit;
+	constructor(limit, message) {
+		super(message);
+		this.name = "ArchiveWalkLimitError";
+		this.limit = limit;
+	}
+};
+function walkArchive(bytes, options = {}) {
+	const maxDepth = options.maxDepth ?? 8;
+	const maxTotalBytes = options.maxTotalBytes ?? 536870912;
+	if (!isZipArchive(bytes)) throw new Error("walkArchive input is not a ZIP archive (leading magic bytes are not PK\\x03\\x04 or PK\\x05\\x06)");
+	const entries = [];
+	let totalBytes = 0;
+	visit(bytes, []);
+	return entries;
+	function visit(archive, ancestors) {
+		if (ancestors.length + 1 > maxDepth) throw new ArchiveWalkLimitError("depth", `archive nesting exceeds the maximum walk depth of ${maxDepth} at ${ancestors.join(" > ")}`);
+		for (const [path, entryBytes] of Object.entries(unzipPackage(archive))) {
+			totalBytes += entryBytes.length;
+			if (totalBytes > maxTotalBytes) throw new ArchiveWalkLimitError("total-bytes", `cumulative decompressed size of the walk exceeded the ${maxTotalBytes}-byte budget at ${path}`);
+			entries.push({
+				path,
+				ancestors,
+				bytes: entryBytes
+			});
+			if (isZipArchive(entryBytes)) visit(entryBytes, [...ancestors, path]);
+		}
+	}
+}
+//#endregion
+exports.ArchiveWalkLimitError = ArchiveWalkLimitError;
+exports.MAX_WALK_DEPTH = MAX_WALK_DEPTH;
+exports.MAX_WALK_TOTAL_BYTES = MAX_WALK_TOTAL_BYTES;
+exports.detectArchiveFormat = detectArchiveFormat;
+exports.isZipArchive = isZipArchive;
+exports.unzipPackage = unzipPackage;
+exports.walkArchive = walkArchive;
+exports.zipPackage = zipPackage;

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+//#region src/zip/container.d.ts
+interface ZipEntry {
+  readonly bytes: Uint8Array<ArrayBuffer>;
+  readonly stored?: boolean;
+}
+declare function unzipPackage(bytes: Uint8Array<ArrayBuffer>): Record<string, Uint8Array<ArrayBuffer>>;
+declare function zipPackage(entries: readonly (readonly [string, ZipEntry])[]): Uint8Array<ArrayBuffer>;
+//#endregion
+//#region src/zip/detect.d.ts
+type ArchiveFormat = 'zip' | 'unknown';
+declare function isZipArchive(bytes: Uint8Array): boolean;
+declare function detectArchiveFormat(bytes: Uint8Array): ArchiveFormat;
+//#endregion
+//#region src/zip/walk.d.ts
+declare const MAX_WALK_DEPTH = 8;
+declare const MAX_WALK_TOTAL_BYTES: number;
+interface ArchiveWalkEntry {
+  readonly path: string;
+  readonly ancestors: readonly string[];
+  readonly bytes: Uint8Array<ArrayBuffer>;
+}
+type ArchiveWalkLimit = 'depth' | 'total-bytes';
+declare class ArchiveWalkLimitError extends Error {
+  readonly limit: ArchiveWalkLimit;
+  constructor(limit: ArchiveWalkLimit, message: string);
+}
+interface WalkArchiveOptions {
+  readonly maxDepth?: number;
+  readonly maxTotalBytes?: number;
+}
+declare function walkArchive(bytes: Uint8Array<ArrayBuffer>, options?: WalkArchiveOptions): ArchiveWalkEntry[];
+//#endregion
+export { ArchiveFormat, ArchiveWalkEntry, ArchiveWalkLimit, ArchiveWalkLimitError, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, WalkArchiveOptions, ZipEntry, detectArchiveFormat, isZipArchive, unzipPackage, walkArchive, zipPackage };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+//#region src/zip/container.d.ts
+interface ZipEntry {
+  readonly bytes: Uint8Array<ArrayBuffer>;
+  readonly stored?: boolean;
+}
+declare function unzipPackage(bytes: Uint8Array<ArrayBuffer>): Record<string, Uint8Array<ArrayBuffer>>;
+declare function zipPackage(entries: readonly (readonly [string, ZipEntry])[]): Uint8Array<ArrayBuffer>;
+//#endregion
+//#region src/zip/detect.d.ts
+type ArchiveFormat = 'zip' | 'unknown';
+declare function isZipArchive(bytes: Uint8Array): boolean;
+declare function detectArchiveFormat(bytes: Uint8Array): ArchiveFormat;
+//#endregion
+//#region src/zip/walk.d.ts
+declare const MAX_WALK_DEPTH = 8;
+declare const MAX_WALK_TOTAL_BYTES: number;
+interface ArchiveWalkEntry {
+  readonly path: string;
+  readonly ancestors: readonly string[];
+  readonly bytes: Uint8Array<ArrayBuffer>;
+}
+type ArchiveWalkLimit = 'depth' | 'total-bytes';
+declare class ArchiveWalkLimitError extends Error {
+  readonly limit: ArchiveWalkLimit;
+  constructor(limit: ArchiveWalkLimit, message: string);
+}
+interface WalkArchiveOptions {
+  readonly maxDepth?: number;
+  readonly maxTotalBytes?: number;
+}
+declare function walkArchive(bytes: Uint8Array<ArrayBuffer>, options?: WalkArchiveOptions): ArchiveWalkEntry[];
+//#endregion
+export { ArchiveFormat, ArchiveWalkEntry, ArchiveWalkLimit, ArchiveWalkLimitError, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, WalkArchiveOptions, ZipEntry, detectArchiveFormat, isZipArchive, unzipPackage, walkArchive, zipPackage };

package/dist/index.js

@@ -0,0 +1,72 @@
+import { unzipSync, zipSync } from "fflate";
+//#region src/zip/container.ts
+function unzipPackage(bytes) {
+	return unzipSync(bytes);
+}
+function zipPackage(entries) {
+	const data = {};
+	for (const [path, entry] of entries) if (entry.stored === true) data[path] = [entry.bytes, { level: 0 }];
+	else data[path] = entry.bytes;
+	return zipSync(data);
+}
+//#endregion
+//#region src/zip/detect.ts
+const ZIP_LOCAL_FILE_HEADER_MAGIC = [
+	80,
+	75,
+	3,
+	4
+];
+const ZIP_END_OF_CENTRAL_DIRECTORY_MAGIC = [
+	80,
+	75,
+	5,
+	6
+];
+function startsWithMagic(bytes, magic) {
+	if (bytes.length < magic.length) return false;
+	for (let i = 0; i < magic.length; i++) if (bytes[i] !== magic[i]) return false;
+	return true;
+}
+function isZipArchive(bytes) {
+	return startsWithMagic(bytes, ZIP_LOCAL_FILE_HEADER_MAGIC) || startsWithMagic(bytes, ZIP_END_OF_CENTRAL_DIRECTORY_MAGIC);
+}
+function detectArchiveFormat(bytes) {
+	return isZipArchive(bytes) ? "zip" : "unknown";
+}
+//#endregion
+//#region src/zip/walk.ts
+const MAX_WALK_DEPTH = 8;
+const MAX_WALK_TOTAL_BYTES = 536870912;
+var ArchiveWalkLimitError = class extends Error {
+	limit;
+	constructor(limit, message) {
+		super(message);
+		this.name = "ArchiveWalkLimitError";
+		this.limit = limit;
+	}
+};
+function walkArchive(bytes, options = {}) {
+	const maxDepth = options.maxDepth ?? 8;
+	const maxTotalBytes = options.maxTotalBytes ?? 536870912;
+	if (!isZipArchive(bytes)) throw new Error("walkArchive input is not a ZIP archive (leading magic bytes are not PK\\x03\\x04 or PK\\x05\\x06)");
+	const entries = [];
+	let totalBytes = 0;
+	visit(bytes, []);
+	return entries;
+	function visit(archive, ancestors) {
+		if (ancestors.length + 1 > maxDepth) throw new ArchiveWalkLimitError("depth", `archive nesting exceeds the maximum walk depth of ${maxDepth} at ${ancestors.join(" > ")}`);
+		for (const [path, entryBytes] of Object.entries(unzipPackage(archive))) {
+			totalBytes += entryBytes.length;
+			if (totalBytes > maxTotalBytes) throw new ArchiveWalkLimitError("total-bytes", `cumulative decompressed size of the walk exceeded the ${maxTotalBytes}-byte budget at ${path}`);
+			entries.push({
+				path,
+				ancestors,
+				bytes: entryBytes
+			});
+			if (isZipArchive(entryBytes)) visit(entryBytes, [...ancestors, path]);
+		}
+	}
+}
+//#endregion
+export { ArchiveWalkLimitError, MAX_WALK_DEPTH, MAX_WALK_TOTAL_BYTES, detectArchiveFormat, isZipArchive, unzipPackage, walkArchive, zipPackage };

package/package.json

@@ -1,5 +1,92 @@
 {
   "name": "archive-codec",
-  "version": "0.0.0",
-  "private": false
+  "version": "1.0.0",
+  "description": "Recursive archive (ZIP-in-ZIP) detection and walking with depth and cumulative decompressed-size guards - zero document-format knowledge, the archive utility package for the documents.js family.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExaDev/archive-codec.git"
+  },
+  "homepage": "https://github.com/ExaDev/archive-codec#readme",
+  "bugs": {
+    "url": "https://github.com/ExaDev/archive-codec/issues"
+  },
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./*": {
+      "types": {
+        "import": "./dist/*.d.ts",
+        "require": "./dist/*.d.cts"
+      },
+      "import": "./dist/*.js",
+      "require": "./dist/*.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "turbo run _build",
+    "_build": "tsdown",
+    "prepublishOnly": "pnpm run lint && pnpm run typecheck && tsdown && publint && attw --pack",
+    "lint": "turbo run _lint",
+    "_lint": "eslint . --fix --cache --max-warnings 0",
+    "lint:check": "eslint . --max-warnings 0",
+    "typecheck": "turbo run _typecheck",
+    "_typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.node.json",
+    "test": "turbo run _test",
+    "_test": "vitest run",
+    "test:watch": "vitest",
+    "test:workers": "turbo run _test:workers",
+    "_test:workers": "vitest run --config vitest.workers.config.ts",
+    "prepare": "husky"
+  },
+  "packageManager": "pnpm@11.6.0",
+  "dependencies": {
+    "fflate": "^0.8.2"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@cloudflare/vitest-pool-workers": "^0.20.1",
+    "@commitlint/cli": "^21.2.1",
+    "@commitlint/config-conventional": "^21.2.0",
+    "@eslint/js": "^10.0.1",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/git": "^11.0.1",
+    "@types/node": "^26.1.2",
+    "eslint": "^10.8.0",
+    "globals": "^17.8.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.2.0",
+    "publint": "^0.3.21",
+    "semantic-release": "^25.0.8",
+    "tsdown": "^0.22.13",
+    "turbo": "^2.10.8",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.65.0",
+    "vitest": "^4.1.10"
+  },
+  "lint-staged": {
+    "*.ts": "eslint --fix"
+  }
 }