@stll/folio-core 0.64.1 → 0.65.0

package/dist/docx/unzip.js

@@ -1,13 +1,12 @@
 import { bytesToDataUrl } from "../utils/base64.js";
-import { encodeUtf8 } from "../utils/textEncoding.js";
-import { compressionRatioLimitFor, countCentralDirectoryRecords, createInflationBudget, exceedsCompressionRatio, getZipEntrySizes, inflateEntryWithinLimits, isStoredZipEntry } from "./archiveInflation.js";
+import { DOCX_COMPRESSION_RATIO_GRACE_BYTES, isRatioBoundedPart } from "./archiveInflation.js";
 import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "./encryption/containerFormat.js";
 import { openDocxBuffer } from "./encryption/openEncryptedDocx.js";
 import { RASTER_MIME_TYPES, detectRasterMimeType } from "./rasterMime.js";
 import { decodeXmlBytes } from "./xmlEncoding.js";
 import { FOLIO_XML_RESOURCE_LIMITS, assertXmlResourceLimits, createXmlPackageBudget } from "./xmlResourceLimits.js";
-import JSZip from "jszip";
-import { writeZipPart } from "@stll/docx-core/zip";
+import { Result } from "better-result";
+import { ZipArchive, ZipError } from "@stll/docx-core/zip";
 // src/docx/unzip.ts
 /**
 * DOCX Unzipper
@@ -116,12 +115,10 @@ async function unzipDocx(buffer, options = {}, { verifyUnreadEntries = true } =
 	const zipBuffer = containerType === DOCX_CONTAINER_TYPES.ZIP ? buffer : await openDocxBuffer(buffer, { password: options.password });
 	if (zipBuffer.byteLength > limits.maxInputBytes) throw new DocxSecurityError("DOCX file exceeds the maximum allowed size");
 	const wasEncrypted = containerType === DOCX_CONTAINER_TYPES.CFB;
-	const maxRecords = limits.maxFiles * 2;
-	if (countCentralDirectoryRecords(new Uint8Array(zipBuffer), maxRecords) > maxRecords) throw new DocxSecurityError("DOCX file contains too many entries");
-	const loaded = await loadDocxZip(zipBuffer, limits.maxFiles);
+	const loaded = await loadDocxZip(zipBuffer, limits);
 	if (loaded.buffer.byteLength > limits.maxInputBytes) throw new DocxSecurityError("DOCX file exceeds the maximum allowed size");
 	const { zip } = loaded;
-	const entries = Object.entries(zip.files).filter(([, file]) => !file.dir);
+	const entries = zip.entries();
 	if (entries.length > limits.maxFiles) throw new DocxSecurityError("DOCX file contains too many entries");
 	const content = {
 		documentXml: null,
@@ -152,79 +149,46 @@ async function unzipDocx(buffer, options = {}, { verifyUnreadEntries = true } =
 		warnings: [],
 		wasEncrypted
 	};
-	let totalUncompressedBytes = 0;
-	const inflationBudget = createInflationBudget(limits.maxTotalUncompressedBytes);
 	const extractionTasks = [];
-	const verifyEntry = (file, path) => {
-		if (!verifyUnreadEntries || isStoredZipEntry(file)) return;
+	const verifyEntry = (file) => {
+		if (!verifyUnreadEntries) return;
 		extractionTasks.push(async () => {
-			await verifyEntryWithinLimits({
-				file,
-				path,
-				limits,
-				budget: inflationBudget
-			});
+			await verifyEntryData(file);
 			return null;
 		});
 	};
-	const inflate = async (file, maxEntryBytes) => await inflateEntryWithinLimits({
-		entry: file,
-		maxEntryBytes,
-		maxCompressionRatio: compressionRatioLimitFor(file.name, limits.maxCompressionRatio),
-		budget: inflationBudget
-	});
-	for (const [path, file] of entries) {
-		if (!isSafeDocxPath(path)) throw new DocxSecurityError("DOCX file contains an unsafe entry path");
-		const { compressedBytes, uncompressedBytes: declaredSize } = getZipEntrySizes(file);
-		if (declaredSize !== null) {
-			totalUncompressedBytes += declaredSize;
-			if (totalUncompressedBytes > limits.maxTotalUncompressedBytes) throw new DocxSecurityError("DOCX file expands beyond the maximum allowed size");
-			if (exceedsCompressionRatio({
-				inflatedBytes: declaredSize,
-				compressedBytes,
-				maxRatio: compressionRatioLimitFor(path, limits.maxCompressionRatio)
-			})) throw new DocxSecurityError(`DOCX entry exceeds the maximum compression ratio: ${path}`);
-		}
+	for (const file of entries) {
+		const { path, size: declaredSize } = file;
 		if (!isParsedDocxEntry(path)) {
-			verifyEntry(file, path);
+			verifyEntry(file);
 			continue;
 		}
 		const lowerPath = path.toLowerCase();
 		if (lowerPath.endsWith(".xml") || lowerPath.endsWith(".rels")) {
 			assertEntrySize(path, declaredSize, limits.maxXmlBytes);
 			if (options.extractAllXml === false && !shouldExtractXmlPart(lowerPath)) {
-				verifyEntry(file, path);
+				verifyEntry(file);
 				continue;
 			}
-			extractionTasks.push(async () => {
-				const result = await inflate(file, limits.maxXmlBytes);
-				if (!result.ok) throw inflationLimitError(result.limit, path);
-				return {
-					type: "xml",
-					path,
-					lowerPath,
-					content: decodeXmlBytes(result.bytes)
-				};
-			});
+			extractionTasks.push(async () => ({
+				type: "xml",
+				path,
+				lowerPath,
+				content: decodeXmlBytes(await readEntry(file))
+			}));
 		} else if (lowerPath.startsWith("word/media/")) {
 			const mimeType = getMediaMimeType(path);
 			if (!limits.allowedMediaMimeTypes.has(mimeType)) {
-				verifyEntry(file, path);
+				verifyEntry(file);
 				continue;
 			}
 			if (isEntryTooLarge(declaredSize, limits.maxMediaBytes)) {
 				content.warnings.push(`Skipped oversized media file: ${path}; original entry preserved for round-trip.`);
-				verifyEntry(file, path);
+				verifyEntry(file);
 				continue;
 			}
 			extractionTasks.push(async () => {
-				const result = await inflate(file, limits.maxMediaBytes);
-				if (!result.ok) {
-					if (result.limit !== "entry") throw inflationLimitError(result.limit, path);
-					content.warnings.push(`Skipped oversized media file: ${path}; original entry preserved for round-trip.`);
-					return null;
-				}
-				const binaryContent = result.bytes.buffer;
+				const binaryContent = (await readEntry(file)).buffer;
 				const effectiveMimeType = RASTER_MIME_TYPES.has(mimeType) ? detectRasterMimeType(binaryContent) : mimeType;
 				if (!effectiveMimeType || !limits.allowedMediaMimeTypes.has(effectiveMimeType) || !isMediaContentAllowed(binaryContent, effectiveMimeType)) return null;
 				return {
@@ -236,30 +200,18 @@ async function unzipDocx(buffer, options = {}, { verifyUnreadEntries = true } =
 			});
 		} else if (lowerPath.startsWith("word/fonts/")) {
 			if (isEntryTooLarge(declaredSize, limits.maxFontBytes)) {
-				verifyEntry(file, path);
+				verifyEntry(file);
 				continue;
 			}
-			extractionTasks.push(async () => {
-				const result = await inflate(file, limits.maxFontBytes);
-				if (!result.ok) {
-					if (result.limit !== "entry") throw inflationLimitError(result.limit, path);
-					return null;
-				}
-				return {
-					type: "font",
-					path,
-					content: result.bytes.buffer
-				};
-			});
-		} else verifyEntry(file, path);
+			extractionTasks.push(async () => ({
+				type: "font",
+				path,
+				content: (await readEntry(file)).buffer
+			}));
+		} else verifyEntry(file);
 	}
-	if (exceedsCompressionRatio({
-		inflatedBytes: totalUncompressedBytes,
-		compressedBytes: loaded.buffer.byteLength,
-		maxRatio: limits.maxCompressionRatio
-	})) throw new DocxSecurityError("DOCX file exceeds the maximum compression ratio");
 	const xmlBudget = createXmlPackageBudget();
-	for (const extracted of await runExtractionTasks(extractionTasks, inflationBudget)) {
+	for (const extracted of await runExtractionTasks(extractionTasks)) {
 		if (!extracted) continue;
 		if (extracted.type === "xml") {
 			assignXmlContent(content, extracted, limits, xmlBudget);
@@ -284,18 +236,10 @@ const replaceRawDocxXmlParts = async (content, parts) => {
 			lowerPath: path.toLowerCase(),
 			content: xmlContent
 		});
-		writeZipPart({
-			zip: content.originalZip,
-			path,
-			data: encodeUtf8(xmlContent)
-		});
+		content.originalZip.set(path, xmlContent);
 		identitiesChanged = true;
 	}
-	if (identitiesChanged) content.originalBuffer = await content.originalZip.generateAsync({
-		type: "arraybuffer",
-		compression: "DEFLATE",
-		compressionOptions: { level: 1 }
-	});
+	if (identitiesChanged) content.originalBuffer = (await content.originalZip.generate({ level: 1 })).buffer;
 };
 /**
 * Preflight every XML part the unzip retains, not a named few.
@@ -349,80 +293,111 @@ const indexXmlContent = (content, { path, lowerPath, content: xmlContent }) => {
 		content.footers.set(filename, xmlContent);
 	}
 };
-function inflationLimitError(limit, path) {
-	switch (limit) {
-		case "declared-size": return new DocxSecurityError(`DOCX entry inflates past its declared size: ${path}`);
-		case "compression-ratio": return new DocxSecurityError(`DOCX entry exceeds the maximum compression ratio: ${path}`);
-		case "entry": return new DocxSecurityError(`DOCX entry exceeds maximum size: ${path}`);
-		case "total": return new DocxSecurityError("DOCX file expands beyond the maximum allowed size");
-		case "aborted": return new DocxSecurityError(`DOCX entry was not read after another entry failed: ${path}`);
+/** The error the unzip reports for an archive or entry the reader refused. */
+function docxErrorFor(error) {
+	const path = error.path ?? "";
+	switch (error.reason) {
+		case "declared-size-exceeded": return new DocxSecurityError(`DOCX entry inflates past its declared size: ${path}`);
+		case "compression-ratio": return new DocxSecurityError(error.path === void 0 ? "DOCX file exceeds the maximum compression ratio" : `DOCX entry exceeds the maximum compression ratio: ${path}`);
+		case "too-many-entries": return new DocxSecurityError("DOCX file contains too many entries");
+		case "entry-too-large":
+		case "total-too-large": return new DocxSecurityError("DOCX file expands beyond the maximum allowed size");
+		case "invalid-entry-name": return new DocxSecurityError("DOCX file contains an unsafe entry path");
+		case "malformed":
+		case "unsupported":
+		case "duplicate-entry":
+		case "corrupt-entry": return error;
 	}
 }
+const rethrowRead = (error) => {
+	throw error instanceof ZipError ? docxErrorFor(error) : error;
+};
+/** An extracted entry's bytes; inflation stops at its declared size. */
+async function readEntry(file) {
+	const read = await Result.tryPromise({
+		try: async () => await file.bytes(),
+		catch: (cause) => cause
+	});
+	return Result.isOk(read) ? read.value : rethrowRead(read.error);
+}
+/**
+* Inflate an entry without keeping it, to bound what a later read of it can
+* produce. Data past the declared size refuses the package. A corrupt entry
+* does not: it was never going to be read here, a later read fails the same
+* way, and refusing the whole document over a part folio does not model
+* would be a regression.
+*/
+async function verifyEntryData(file) {
+	const read = await Result.tryPromise({
+		try: async () => await file.bytes(),
+		catch: (cause) => cause
+	});
+	if (Result.isOk(read)) return;
+	const error = read.error;
+	if (!(error instanceof ZipError) || error.reason === "declared-size-exceeded") rethrowRead(error);
+}
 /**
 * Run extraction tasks a few at a time, in order, keeping their results in
-* task order. The first failure marks the shared budget aborted, which stops
-* the streams still running at their next chunk and leaves the queued tasks
-* unstarted.
+* task order. The first failure leaves the queued tasks unstarted.
 */
-async function runExtractionTasks(tasks, budget) {
+async function runExtractionTasks(tasks) {
 	const results = Array.from({ length: tasks.length }, () => null);
 	let next = 0;
+	let aborted = false;
 	const worker = async () => {
-		while (next < tasks.length && !budget.aborted) {
+		while (next < tasks.length && !aborted) {
 			const index = next;
 			next += 1;
 			const task = tasks[index];
 			if (!task) return;
-			try {
-				results[index] = await task();
-			} catch (error) {
-				budget.aborted = true;
-				throw error;
+			const result = await Result.tryPromise({
+				try: async () => await task(),
+				catch: (cause) => cause
+			});
+			if (Result.isError(result)) {
+				aborted = true;
+				throw result.error;
 			}
+			results[index] = result.value;
 		}
 	};
 	await Promise.all(Array.from({ length: Math.min(EXTRACTION_CONCURRENCY, tasks.length) }, async () => await worker()));
 	return results;
 }
-/**
-* Inflate an entry without keeping it, to bound what a later read of it can
-* produce. A limit refuses the package. A corrupt entry does not: it was never
-* going to be read here, a later read stops at the same byte, and refusing
-* the whole document over a part folio does not model would be a regression.
-*/
-async function verifyEntryWithinLimits({ file, path, limits, budget }) {
-	let result;
-	try {
-		result = await inflateEntryWithinLimits({
-			entry: file,
-			maxEntryBytes: Number.POSITIVE_INFINITY,
-			maxCompressionRatio: compressionRatioLimitFor(path, limits.maxCompressionRatio),
-			budget,
-			retain: false
-		});
-	} catch {
-		return;
-	}
-	if (!result.ok) throw inflationLimitError(result.limit, path);
-}
-async function loadDocxZip(buffer, maxFiles) {
-	try {
-		return {
-			zip: await JSZip.loadAsync(buffer),
-			buffer
-		};
-	} catch (error) {
-		const repairedBuffer = repairTruncatedEndOfCentralDirectory(buffer, maxFiles);
-		if (!repairedBuffer) throw error;
-		try {
-			return {
-				zip: await JSZip.loadAsync(repairedBuffer),
-				buffer: repairedBuffer
-			};
-		} catch {
-			throw error;
-		}
-	}
+/** Package limits as the archive reader enforces them. */
+const zipReadOptionsFor = (limits) => ({
+	limits: {
+		maxEntries: limits.maxFiles * 2,
+		maxEntryBytes: limits.maxTotalUncompressedBytes,
+		maxTotalBytes: limits.maxTotalUncompressedBytes,
+		maxCompressionRatio: limits.maxCompressionRatio,
+		compressionRatioGraceBytes: DOCX_COMPRESSION_RATIO_GRACE_BYTES
+	},
+	isCompressionRatioExempt: (path) => !isRatioBoundedPart(path)
+});
+async function loadDocxZip(buffer, limits) {
+	const options = zipReadOptionsFor(limits);
+	const read = await Result.tryPromise({
+		try: async () => await ZipArchive.read(buffer, options),
+		catch: (cause) => cause
+	});
+	if (Result.isOk(read)) return {
+		zip: read.value,
+		buffer
+	};
+	const error = read.error;
+	if (!(error instanceof ZipError) || error.reason !== "malformed") return rethrowRead(error);
+	const repairedBuffer = repairTruncatedEndOfCentralDirectory(buffer, limits.maxFiles);
+	if (!repairedBuffer) throw error;
+	const repaired = await Result.tryPromise({
+		try: async () => await ZipArchive.read(repairedBuffer, options),
+		catch: (cause) => cause
+	});
+	if (Result.isOk(repaired)) return {
+		zip: repaired.value,
+		buffer: repairedBuffer
+	};
+	throw error;
 }
 function repairTruncatedEndOfCentralDirectory(buffer, maxFiles) {
 	const bytes = new Uint8Array(buffer);
@@ -520,14 +495,11 @@ function isParsedDocxEntry(path) {
 	if (!(lowerPath.endsWith(".xml") || lowerPath.endsWith(".rels"))) return false;
 	return lowerPath === "[content_types].xml" || lowerPath.startsWith("_rels/") || lowerPath.startsWith("docprops/") || lowerPath.startsWith("word/") || lowerPath.startsWith("customxml/");
 }
-function getEntryUncompressedSize(file) {
-	return getZipEntrySizes(file).uncompressedBytes;
-}
 function assertEntrySize(path, declaredSize, maxBytes) {
 	if (isEntryTooLarge(declaredSize, maxBytes)) throw new DocxSecurityError(`DOCX entry exceeds maximum size: ${path}`);
 }
 function isEntryTooLarge(declaredSize, maxBytes) {
-	return declaredSize !== null && declaredSize > maxBytes;
+	return declaredSize > maxBytes;
 }
 function isMediaContentAllowed(data, mimeType) {
 	if (RASTER_MIME_TYPES.has(mimeType)) return detectRasterMimeType(data) === mimeType;
@@ -548,7 +520,7 @@ function isMediaContentAllowed(data, mimeType) {
 */
 function getFileList(content) {
 	const files = [];
-	for (const path of Object.keys(content.originalZip.files)) if (!content.originalZip.files[path]?.dir && isParsedDocxEntry(path)) files.push(path);
+	for (const path of content.originalZip.paths()) if (isParsedDocxEntry(path)) files.push(path);
 	return files.toSorted();
 }
 /**
@@ -591,11 +563,11 @@ function mediaToDataUrl(data, mimeType) {
 * @returns File content as string or ArrayBuffer, or null if not found
 */
 function extractFile(content, path) {
-	const file = content.originalZip.file(path);
+	const file = content.originalZip.entry(path);
 	if (!file || !isParsedDocxEntry(path)) return Promise.resolve(null);
 	const lowerPath = path.toLowerCase();
-	if (lowerPath.endsWith(".xml") || lowerPath.endsWith(".rels")) return file.async("uint8array").then(decodeXmlBytes);
-	return file.async("arraybuffer");
+	if (lowerPath.endsWith(".xml") || lowerPath.endsWith(".rels")) return file.bytes().then(decodeXmlBytes);
+	return file.arrayBuffer();
 }
 /**
 * Check if a file exists in the DOCX
@@ -605,7 +577,7 @@ function extractFile(content, path) {
 * @returns true if file exists
 */
 function hasFile(content, path) {
-	return content.originalZip.file(path) !== null;
+	return content.originalZip.has(path);
 }
 /**
 * Get summary of DOCX content
@@ -627,7 +599,7 @@ function getContentSummary(content) {
 		footerCount: content.footers.size,
 		mediaCount: content.media.size,
 		fontCount: content.fonts.size,
-		totalFiles: Object.keys(content.originalZip.files).filter((p) => !content.originalZip.files[p]?.dir).length
+		totalFiles: content.originalZip.paths().length
 	};
 }
-export { DocxSecurityError, extractFile, getContentSummary, getEntryUncompressedSize, getFileList, getMediaMimeType, hasFile, mediaToDataUrl, replaceRawDocxXmlParts, unzipDocx };
+export { DocxSecurityError, extractFile, getContentSummary, getFileList, getMediaMimeType, hasFile, mediaToDataUrl, replaceRawDocxXmlParts, unzipDocx };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/folio-core",
-  "version": "0.64.1",
+  "version": "0.65.0",
   "description": "Headless, framework-neutral core of folio: the OOXML (.docx) parser, document model, ProseMirror integration, and page-layout engine. No React.",
   "keywords": [
     "document-model",
@@ -171,16 +171,15 @@
     "perf": "bun scripts/profile-editor.ts"
   },
   "dependencies": {
-    "@stll/docx-core": "^0.39.2",
+    "@stll/docx-core": "^0.40.0",
     "@stll/docx-utils": "^0.2.0",
     "@stll/template-conditions": "^0.6.2",
-    "@stll/utf8-boundaries": "0.1.2",
+    "@stll/utf8-boundaries": "0.2.0",
     "better-result": "3.0.1",
     "csstype": "^3.1.3",
     "dompurify": "^3.4.17",
     "fast-xml-parser": "^5.11.2",
     "hyphen": "1.14.1",
-    "jszip": "3.10.2",
     "utif2": "^4.1.0",
     "valibot": "1.5.0"
   },