archive-codec 1.0.2 → 1.1.1

package/README.md

@@ -2,11 +2,13 @@
 
 [![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/documents.js/tree/main/packages/archive-codec) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/archive-codec) [![npm version](https://img.shields.io/npm/v/archive-codec)](https://www.npmjs.com/package/archive-codec) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/documents.js/ci.yml?branch=main)](https://github.com/ExaDev/documents.js/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](../../README.md). Worker-isomorphic: the same code runs under Node and inside a Cloudflare Workers isolate.
+> ZIP-in-ZIP recursive walking under depth and cumulative decompressed-size guards, and bounded classic OLE compound-file ([MS-CFB]) reading — zero document-format knowledge, the archive and container utility package for the [documents.js family](../../README.md). 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). Its first family consumer is `ooxml.js`'s OLE embedded-object recovery — [documents.js#733](https://github.com/ExaDev/documents.js/issues/733) (pptx, `p:oleObj`) and [documents.js#734](https://github.com/ExaDev/documents.js/issues/734) (docx, `o:OLEObject`): an OLE payload part's bytes are checked through `isZipArchive` and, when they are a ZIP, decoded as a nested OOXML package behind this package's guarded walk — the bounded inflate that populates `document-schema.js`'s `ContentEmbeddedObject`/`ContentEmbeddedObjectBlock` (the same vocabulary odf.js embeds formula sub-documents through) with a genuinely recovered sub-document.
 
-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.**
+[documents.js#739](https://github.com/ExaDev/documents.js/issues/739) widened the charter from that ZIP-only v1 scope to the classic OLE compound file, recording the decision explicitly rather than by accident (mirroring the #564 reasoning): real-world Word and PowerPoint files frequently store the embeddee as a `.bin` compound file at `word|ppt/embeddings/oleObject1.bin`, and a CFB reader is container knowledge exactly the way ZIP structure is — sectors, FAT chains, and directory entries, never that any stream is a document. The same recovery now unwraps such a payload's `Package` stream ([MS-OLEDS]'s OLE packaging of the real file) through this package and feeds the packaged ZIP to the unchanged nested decode.
+
+Scope: **ZIP containers** (read and write over [`fflate`](https://github.com/101arrowz/fflate), recursive walking of ZIP-in-ZIP entries) and **classic OLE compound files** (bounded [MS-CFB] reading, plus the OLE Package stream unwrapping). **tar and gzip are explicitly out of scope.**
 
 ## Getting started
 
@@ -14,23 +16,36 @@ Requires Node.js `>=20` and pnpm `11.6.0`.
 
 ```sh
 pnpm install
-pnpm build          # tsdown -> dist/ (ESM + CJS + .d.ts)
+pnpm build          # tsdown -> dist/ (ESM + CJS + .d.ts, one file set per src module)
 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           # vitest run --project unit
+pnpm test:watch     # vitest --project unit
 pnpm test:workers   # vitest run --config vitest.workers.config.ts, inside a real Cloudflare Workers (workerd) isolate
+pnpm test:smoke     # builds dist/, then loads the built ESM and CJS barrels and every advertised deep import
 ```
 
 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
 
+Every module is importable by package-relative path as well as through the barrel — `tsdown` builds one dist file per src module (`root: 'src'`, the same layout ooxml.js ships), and `package.json`'s `./*` exports wildcard maps each subpath onto it:
+
+```ts
+import { readCompoundFile } from 'archive-codec/cfb/read';
+import { walkArchive } from 'archive-codec/zip/walk';
+```
+
+The smoke suite (`test/smoke.test.mjs`) is the guard on that advertisement: it loads each module below from the built `dist/` in both module systems, so a build config that stops serving an advertised subpath fails the suite — neither publint nor `attw` catches a wildcard whose targets are missing.
+
 | Module | Exports |
 |---|---|
 | `zip/container` | `zipPackage` (ordered-entries ZIP write with stored-uncompressed support), `unzipPackage`, `ZipEntry` |
-| `zip/detect` | `detectArchiveFormat` (`'zip' \| 'unknown'`), `isZipArchive`, `ArchiveFormat` |
+| `zip/detect` | `detectArchiveFormat` (`'zip' \| 'cfb' \| 'unknown'`), `isZipArchive`, `ArchiveFormat` |
 | `zip/walk` | `walkArchive` (recursive ZIP-in-ZIP walking), `ArchiveWalkEntry`, `ArchiveWalkLimitError`, `MAX_WALK_DEPTH`, `MAX_WALK_TOTAL_BYTES`, `WalkArchiveOptions` |
+| `cfb/detect` | `isCompoundFile` (the `D0 CF 11 E0 …` magic-byte check) |
+| `cfb/read` | `readCompoundFile` (bounded [MS-CFB] stream extraction), `CompoundFileStream`, `CompoundFileFormatError`, `MAX_CFB_TOTAL_STREAM_BYTES`, `ReadCompoundFileOptions` |
+| `cfb/ole-package` | `readOlePackage` (OLE Package stream unwrapping), `OlePackage`, `OlePackageFormatError` |
 
 ### Recursive walking
 
@@ -49,6 +64,28 @@ for (const entry of walkArchive(docxBytes)) {
 
 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.
 
+### Compound files
+
+```ts
+import { readCompoundFile, readOlePackage } from 'archive-codec';
+
+// Every stream of a classic OLE compound file, with its storage path.
+// Throws CompoundFileFormatError on any structural nonconformance.
+for (const stream of readCompoundFile(oleBinBytes)) {
+  stream.path;  // e.g. 'Package' -- root-level, or 'ObjectStorage/Package'
+  stream.bytes; // the stream's content
+}
+
+// The OLE packaging a Word/PowerPoint embed wraps the real file in before
+// storing it as the 'Package' stream: label, paths, and the file's bytes.
+const packageStream = readCompoundFile(oleBinBytes).find((s) => s.path === 'Package');
+if (packageStream !== undefined) {
+  readOlePackage(packageStream.bytes).fileBytes; // often a ZIP for a modern embed
+}
+```
+
+Reading is bounded the same way walking is: chain cycles and out-of-range sectors fail against bounds derived from the file's own sector count, and one cumulative extracted-bytes budget (`MAX_CFB_TOTAL_STREAM_BYTES`, 512 MiB — the same figure the family grants one decompressed stream) bounds the multiplication a hostile FAT gains by aliasing one sector into many streams. Every structural failure throws rather than truncating — a malformed compound file fails whole, never a partial stream listing that looks complete. Version 3 (512-byte sectors) and version 4 (4096-byte) files both read; the mini-FAT path every stream shorter than the header's cutoff takes is first-class, because a small real-world embed genuinely lands there.
+
 ### 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.
@@ -57,7 +94,7 @@ Both guards throw rather than truncate: an input outside the contract must fail
 
 - Worker-isomorphic (see the [family-wide convention](../../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).
+- Zero document-format knowledge: this package knows bytes and container structure — ZIP entries, compound-file sectors and directory entries, the OLE packaging wrapper — never that any entry or stream 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).
 
 ## Install
 

package/dist/cfb/detect.cjs

@@ -0,0 +1,18 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_magic = require("../magic.cjs");
+//#region src/cfb/detect.ts
+const COMPOUND_FILE_MAGIC = [
+	208,
+	207,
+	17,
+	224,
+	161,
+	177,
+	26,
+	225
+];
+function isCompoundFile(bytes) {
+	return require_magic.startsWithMagic(bytes, COMPOUND_FILE_MAGIC);
+}
+//#endregion
+exports.isCompoundFile = isCompoundFile;

package/dist/cfb/detect.d.cts

@@ -0,0 +1,4 @@
+//#region src/cfb/detect.d.ts
+declare function isCompoundFile(bytes: Uint8Array): boolean;
+//#endregion
+export { isCompoundFile };

package/dist/cfb/detect.d.ts

@@ -0,0 +1,4 @@
+//#region src/cfb/detect.d.ts
+declare function isCompoundFile(bytes: Uint8Array): boolean;
+//#endregion
+export { isCompoundFile };

package/dist/cfb/detect.js

@@ -0,0 +1,17 @@
+import { startsWithMagic } from "../magic.js";
+//#region src/cfb/detect.ts
+const COMPOUND_FILE_MAGIC = [
+	208,
+	207,
+	17,
+	224,
+	161,
+	177,
+	26,
+	225
+];
+function isCompoundFile(bytes) {
+	return startsWithMagic(bytes, COMPOUND_FILE_MAGIC);
+}
+//#endregion
+export { isCompoundFile };

package/dist/cfb/ole-package.cjs

@@ -0,0 +1,42 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/cfb/ole-package.ts
+var OlePackageFormatError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "OlePackageFormatError";
+	}
+};
+const ANSI_DECODER = new TextDecoder("windows-1252");
+function readZeroTerminated(bytes, offset, fieldName) {
+	let end = offset;
+	while (end < bytes.length && bytes[end] !== 0) end++;
+	if (end >= bytes.length) throw new OlePackageFormatError(`Package stream ends inside its ${fieldName} string with no terminator`);
+	return {
+		value: ANSI_DECODER.decode(bytes.subarray(offset, end)),
+		next: end + 1
+	};
+}
+function readOlePackage(bytes) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let offset = 2;
+	const label = readZeroTerminated(bytes, offset, "label");
+	offset = label.next;
+	const sourcePath = readZeroTerminated(bytes, offset, "source path");
+	offset = sourcePath.next;
+	offset += 8;
+	const tempPath = readZeroTerminated(bytes, offset, "temp path");
+	offset = tempPath.next;
+	if (offset + 4 > bytes.length) throw new OlePackageFormatError("Package stream ends before its packaged file size field");
+	const fileByteCount = view.getUint32(offset, true);
+	offset += 4;
+	if (offset + fileByteCount > bytes.length) throw new OlePackageFormatError(`Package stream declares ${fileByteCount} packaged-file bytes but holds only ${bytes.length - offset}`);
+	return {
+		label: label.value,
+		sourcePath: sourcePath.value,
+		tempPath: tempPath.value,
+		fileBytes: bytes.slice(offset, offset + fileByteCount)
+	};
+}
+//#endregion
+exports.OlePackageFormatError = OlePackageFormatError;
+exports.readOlePackage = readOlePackage;

package/dist/cfb/ole-package.d.cts

@@ -0,0 +1,13 @@
+//#region src/cfb/ole-package.d.ts
+declare class OlePackageFormatError extends Error {
+  constructor(message: string);
+}
+interface OlePackage {
+  readonly label: string;
+  readonly sourcePath: string;
+  readonly tempPath: string;
+  readonly fileBytes: Uint8Array<ArrayBuffer>;
+}
+declare function readOlePackage(bytes: Uint8Array<ArrayBuffer>): OlePackage;
+//#endregion
+export { OlePackage, OlePackageFormatError, readOlePackage };

package/dist/cfb/ole-package.d.ts

@@ -0,0 +1,13 @@
+//#region src/cfb/ole-package.d.ts
+declare class OlePackageFormatError extends Error {
+  constructor(message: string);
+}
+interface OlePackage {
+  readonly label: string;
+  readonly sourcePath: string;
+  readonly tempPath: string;
+  readonly fileBytes: Uint8Array<ArrayBuffer>;
+}
+declare function readOlePackage(bytes: Uint8Array<ArrayBuffer>): OlePackage;
+//#endregion
+export { OlePackage, OlePackageFormatError, readOlePackage };

package/dist/cfb/ole-package.js

@@ -0,0 +1,40 @@
+//#region src/cfb/ole-package.ts
+var OlePackageFormatError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "OlePackageFormatError";
+	}
+};
+const ANSI_DECODER = new TextDecoder("windows-1252");
+function readZeroTerminated(bytes, offset, fieldName) {
+	let end = offset;
+	while (end < bytes.length && bytes[end] !== 0) end++;
+	if (end >= bytes.length) throw new OlePackageFormatError(`Package stream ends inside its ${fieldName} string with no terminator`);
+	return {
+		value: ANSI_DECODER.decode(bytes.subarray(offset, end)),
+		next: end + 1
+	};
+}
+function readOlePackage(bytes) {
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	let offset = 2;
+	const label = readZeroTerminated(bytes, offset, "label");
+	offset = label.next;
+	const sourcePath = readZeroTerminated(bytes, offset, "source path");
+	offset = sourcePath.next;
+	offset += 8;
+	const tempPath = readZeroTerminated(bytes, offset, "temp path");
+	offset = tempPath.next;
+	if (offset + 4 > bytes.length) throw new OlePackageFormatError("Package stream ends before its packaged file size field");
+	const fileByteCount = view.getUint32(offset, true);
+	offset += 4;
+	if (offset + fileByteCount > bytes.length) throw new OlePackageFormatError(`Package stream declares ${fileByteCount} packaged-file bytes but holds only ${bytes.length - offset}`);
+	return {
+		label: label.value,
+		sourcePath: sourcePath.value,
+		tempPath: tempPath.value,
+		fileBytes: bytes.slice(offset, offset + fileByteCount)
+	};
+}
+//#endregion
+export { OlePackageFormatError, readOlePackage };

package/dist/cfb/read.cjs

@@ -0,0 +1,206 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_cfb_detect = require("./detect.cjs");
+//#region src/cfb/read.ts
+const ENDOFCHAIN = 4294967294;
+const FREESECT = 4294967295;
+const FATSECT = 4294967293;
+const DIFSECT = 4294967292;
+const NOSTREAM = 4294967295;
+const HEADER_SIZE = 512;
+const HEADER_DIFAT_ENTRIES = 109;
+const OBJECT_TYPE_STORAGE = 1;
+const OBJECT_TYPE_STREAM = 2;
+const OBJECT_TYPE_ROOT = 5;
+const MAX_CFB_TOTAL_STREAM_BYTES = 536870912;
+var CompoundFileFormatError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CompoundFileFormatError";
+	}
+};
+function u32(view, offset) {
+	return view.getUint32(offset, true);
+}
+function u16(view, offset) {
+	return view.getUint16(offset, true);
+}
+function readCompoundFile(bytes, options = {}) {
+	const maxTotalBytes = options.maxTotalBytes ?? 536870912;
+	if (!require_cfb_detect.isCompoundFile(bytes)) throw new CompoundFileFormatError("readCompoundFile input does not carry the compound-file signature (leading magic bytes are not D0 CF 11 E0 A1 B1 1A E1)");
+	if (bytes.length < HEADER_SIZE) throw new CompoundFileFormatError(`compound file is ${bytes.length} bytes, shorter than the fixed ${HEADER_SIZE}-byte header`);
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const majorVersion = u16(view, 26);
+	if (majorVersion !== 3 && majorVersion !== 4) throw new CompoundFileFormatError(`compound file major version ${majorVersion} is not 3 or 4`);
+	if (u16(view, 28) !== 65534) throw new CompoundFileFormatError("compound file byte order is not little-endian");
+	const sectorShift = u16(view, 30);
+	if (majorVersion === 3 && sectorShift !== 9 || majorVersion === 4 && sectorShift !== 12) throw new CompoundFileFormatError(`compound file sector shift 2^${sectorShift} does not match major version ${majorVersion} (version 3 requires 512-byte sectors, version 4 requires 4096-byte)`);
+	const miniSectorShift = u16(view, 32);
+	if (miniSectorShift !== 6) throw new CompoundFileFormatError(`compound file mini sector shift 2^${miniSectorShift} is not the mandated 64-byte mini sector`);
+	const sectorSize = 1 << sectorShift;
+	const miniSectorSize = 1 << miniSectorShift;
+	const miniStreamCutoff = u32(view, 56);
+	if (miniStreamCutoff < miniSectorSize) throw new CompoundFileFormatError(`compound file mini stream cutoff ${miniStreamCutoff} is smaller than the ${miniSectorSize}-byte mini sector itself`);
+	const firstDirectorySector = u32(view, 48);
+	const firstMiniFatSector = u32(view, 60);
+	const firstDifatSector = u32(view, 68);
+	const sectorCount = Math.floor(bytes.length / sectorSize) - 1;
+	if (sectorCount < 1) throw new CompoundFileFormatError(`compound file holds no complete ${sectorSize}-byte sector after its header`);
+	const sectorOffset = (sector) => (sector + 1) * sectorSize;
+	const sectorBytes = (sector) => bytes.subarray(sectorOffset(sector), sectorOffset(sector) + sectorSize);
+	const fatSectorIds = [];
+	const acceptFatSector = (sector, provenance) => {
+		if (sector === FREESECT) return;
+		if (sector >= sectorCount) throw new CompoundFileFormatError(`${provenance} names FAT sector ${sector}, which is outside the file's ${sectorCount} sectors`);
+		fatSectorIds.push(sector);
+	};
+	for (let i = 0; i < HEADER_DIFAT_ENTRIES; i++) acceptFatSector(u32(view, 76 + i * 4), "the header DIFAT array");
+	let difatSector = firstDifatSector;
+	let difatSectorsWalked = 0;
+	while (difatSector !== ENDOFCHAIN) {
+		if (difatSector >= sectorCount) throw new CompoundFileFormatError(`the DIFAT chain names sector ${difatSector}, which is outside the file's ${sectorCount} sectors`);
+		if (++difatSectorsWalked > sectorCount) throw new CompoundFileFormatError("the DIFAT chain visits more sectors than the file holds, so it must cycle");
+		const difatView = new DataView(bytes.buffer, bytes.byteOffset + sectorOffset(difatSector), sectorSize);
+		const entriesPerDifatSector = sectorSize / 4 - 1;
+		for (let i = 0; i < entriesPerDifatSector; i++) acceptFatSector(u32(difatView, i * 4), "a DIFAT sector");
+		difatSector = u32(difatView, entriesPerDifatSector * 4);
+	}
+	if (fatSectorIds.length === 0) throw new CompoundFileFormatError("compound file declares no FAT sectors, so no sector chain can be walked");
+	const fatBytes = new Uint8Array(fatSectorIds.length * sectorSize);
+	for (let i = 0; i < fatSectorIds.length; i++) fatBytes.set(sectorBytes(fatSectorIds[i] ?? 0), i * sectorSize);
+	const fat = new DataView(fatBytes.buffer);
+	const fatEntry = (sector) => {
+		const offset = sector * 4;
+		if (offset < 0 || offset + 4 > fatBytes.length) throw new CompoundFileFormatError(`FAT entry for sector ${sector} lies beyond the sectors the DIFAT named`);
+		return fat.getUint32(offset, true);
+	};
+	const chainSectorIds = (start) => {
+		const ids = [];
+		let current = start;
+		while (current !== ENDOFCHAIN) {
+			if (current >= sectorCount) throw new CompoundFileFormatError(`a FAT chain steps to sector ${current}, which is outside the file's ${sectorCount} sectors`);
+			if (ids.length >= sectorCount) throw new CompoundFileFormatError("a FAT chain visits more sectors than the file holds, so it must cycle");
+			ids.push(current);
+			const next = fatEntry(current);
+			if (next === FREESECT || next === FATSECT || next === DIFSECT) throw new CompoundFileFormatError(`a FAT chain steps to sector ${current}'s entry ${next}, which is a sector-role marker, not a chain continuation`);
+			current = next;
+		}
+		return ids;
+	};
+	const chainBytes = (start) => {
+		const ids = chainSectorIds(start);
+		const out = new Uint8Array(ids.length * sectorSize);
+		for (let i = 0; i < ids.length; i++) out.set(sectorBytes(ids[i] ?? 0), i * sectorSize);
+		return out;
+	};
+	const directoryBytes = chainBytes(firstDirectorySector);
+	if (directoryBytes.length === 0) throw new CompoundFileFormatError("compound file has an empty directory chain");
+	const directoryView = new DataView(directoryBytes.buffer);
+	const entryCount = directoryBytes.length / 128;
+	const nameDecoder = new TextDecoder("utf-16le");
+	const entries = [];
+	for (let id = 0; id < entryCount; id++) {
+		const base = id * 128;
+		const nameLength = u16(directoryView, base + 64);
+		entries.push({
+			name: nameDecoder.decode(directoryBytes.subarray(base, base + Math.max(0, nameLength - 2))),
+			nameLength,
+			objectType: directoryView.getUint8(base + 66),
+			leftSibling: u32(directoryView, base + 68),
+			rightSibling: u32(directoryView, base + 72),
+			child: u32(directoryView, base + 76),
+			startSector: u32(directoryView, base + 116),
+			size: u32(directoryView, base + 120) + u32(directoryView, base + 124) * 4294967296
+		});
+	}
+	const root = entries[0];
+	if (root === void 0 || root.objectType !== OBJECT_TYPE_ROOT) throw new CompoundFileFormatError("the first directory entry is not the root storage entry (object type 5), as [MS-CFB] 2.6.1 requires");
+	const miniStream = chainBytes(root.startSector).subarray(0, root.size);
+	const miniSectorCount = Math.floor(miniStream.length / miniSectorSize);
+	const miniFatBytes = chainBytes(firstMiniFatSector);
+	const miniFat = new DataView(miniFatBytes.buffer);
+	const miniChainSectorIds = (start) => {
+		const ids = [];
+		let current = start;
+		while (current !== ENDOFCHAIN) {
+			if (current >= miniSectorCount) throw new CompoundFileFormatError(`a mini-FAT chain steps to mini sector ${current}, which is outside the mini stream's ${miniSectorCount} mini sectors`);
+			if (ids.length >= miniSectorCount) throw new CompoundFileFormatError("a mini-FAT chain visits more mini sectors than the mini stream holds, so it must cycle");
+			ids.push(current);
+			const next = miniFat.getUint32(current * 4, true);
+			if (next === FREESECT || next === FATSECT || next === DIFSECT) throw new CompoundFileFormatError(`a mini-FAT chain steps to mini sector ${current}'s entry ${next}, which is a sector-role marker, not a chain continuation`);
+			current = next;
+		}
+		return ids;
+	};
+	let totalExtractedBytes = 0;
+	const extractStream = (entry) => {
+		if (entry.size === 0) return /* @__PURE__ */ new Uint8Array(0);
+		if (entry.size > Number.MAX_SAFE_INTEGER) throw new CompoundFileFormatError(`stream '${entry.name}' declares a size beyond the integer range this reader addresses`);
+		let out;
+		if (entry.size < miniStreamCutoff) {
+			const ids = miniChainSectorIds(entry.startSector);
+			const raw = new Uint8Array(ids.length * miniSectorSize);
+			for (let i = 0; i < ids.length; i++) {
+				const miniSector = ids[i] ?? 0;
+				raw.set(miniStream.subarray(miniSector * miniSectorSize, (miniSector + 1) * miniSectorSize), i * miniSectorSize);
+			}
+			out = raw;
+		} else out = chainBytes(entry.startSector);
+		if (out.length < entry.size) throw new CompoundFileFormatError(`stream '${entry.name}' declares ${entry.size} bytes but its chain holds only ${out.length}`);
+		totalExtractedBytes += entry.size;
+		if (totalExtractedBytes > maxTotalBytes) throw new CompoundFileFormatError(`cumulative extracted stream size exceeded the ${maxTotalBytes}-byte budget at '${entry.name}'`);
+		return out.slice(0, entry.size);
+	};
+	const streams = [];
+	const visited = /* @__PURE__ */ new Set();
+	const stack = [{
+		id: root.child,
+		prefix: "",
+		stage: "descend"
+	}];
+	for (let frame = stack.pop(); frame !== void 0; frame = stack.pop()) if (frame.stage === "descend") {
+		const { id, prefix } = frame;
+		if (id === NOSTREAM) continue;
+		const entry = entries[id];
+		if (id >= entryCount || entry === void 0) throw new CompoundFileFormatError(`the directory tree links to entry ${id}, which is outside the directory's ${entryCount} entries`);
+		if (visited.has(id)) throw new CompoundFileFormatError(`the directory tree reaches entry ${id} twice, so its sibling and child links cycle`);
+		visited.add(id);
+		if (entry.nameLength < 2 || entry.nameLength > 64 || entry.nameLength % 2 === 1) throw new CompoundFileFormatError(`directory entry ${id} declares name length ${entry.nameLength}, which is not an even byte count between 2 and 64`);
+		if (entry.objectType !== OBJECT_TYPE_STORAGE && entry.objectType !== OBJECT_TYPE_STREAM && entry.objectType !== OBJECT_TYPE_ROOT) throw new CompoundFileFormatError(`directory entry ${id} ('${entry.name}') carries object type ${entry.objectType}, which is not a storage (1), stream (2), or root (5) entry`);
+		stack.push({
+			entry,
+			prefix,
+			stage: "self"
+		});
+		stack.push({
+			id: entry.leftSibling,
+			prefix,
+			stage: "descend"
+		});
+	} else if (frame.entry.objectType === OBJECT_TYPE_STREAM) {
+		streams.push({
+			path: frame.prefix + frame.entry.name,
+			bytes: extractStream(frame.entry)
+		});
+		stack.push({
+			id: frame.entry.rightSibling,
+			prefix: frame.prefix,
+			stage: "descend"
+		});
+	} else if (frame.entry.objectType === OBJECT_TYPE_STORAGE) {
+		stack.push({
+			id: frame.entry.rightSibling,
+			prefix: frame.prefix,
+			stage: "descend"
+		});
+		stack.push({
+			id: frame.entry.child,
+			prefix: `${frame.prefix}${frame.entry.name}/`,
+			stage: "descend"
+		});
+	} else throw new CompoundFileFormatError(`the directory tree reaches entry ${frame.entry.name}, which is not a storage or stream entry`);
+	return streams;
+}
+//#endregion
+exports.CompoundFileFormatError = CompoundFileFormatError;
+exports.MAX_CFB_TOTAL_STREAM_BYTES = MAX_CFB_TOTAL_STREAM_BYTES;
+exports.readCompoundFile = readCompoundFile;

package/dist/cfb/read.d.cts

@@ -0,0 +1,15 @@
+//#region src/cfb/read.d.ts
+declare const MAX_CFB_TOTAL_STREAM_BYTES: number;
+declare class CompoundFileFormatError extends Error {
+  constructor(message: string);
+}
+interface CompoundFileStream {
+  readonly path: string;
+  readonly bytes: Uint8Array<ArrayBuffer>;
+}
+interface ReadCompoundFileOptions {
+  readonly maxTotalBytes?: number;
+}
+declare function readCompoundFile(bytes: Uint8Array<ArrayBuffer>, options?: ReadCompoundFileOptions): CompoundFileStream[];
+//#endregion
+export { CompoundFileFormatError, CompoundFileStream, MAX_CFB_TOTAL_STREAM_BYTES, ReadCompoundFileOptions, readCompoundFile };

package/dist/cfb/read.d.ts

@@ -0,0 +1,15 @@
+//#region src/cfb/read.d.ts
+declare const MAX_CFB_TOTAL_STREAM_BYTES: number;
+declare class CompoundFileFormatError extends Error {
+  constructor(message: string);
+}
+interface CompoundFileStream {
+  readonly path: string;
+  readonly bytes: Uint8Array<ArrayBuffer>;
+}
+interface ReadCompoundFileOptions {
+  readonly maxTotalBytes?: number;
+}
+declare function readCompoundFile(bytes: Uint8Array<ArrayBuffer>, options?: ReadCompoundFileOptions): CompoundFileStream[];
+//#endregion
+export { CompoundFileFormatError, CompoundFileStream, MAX_CFB_TOTAL_STREAM_BYTES, ReadCompoundFileOptions, readCompoundFile };