@stll/docx-utils 0.1.2 → 0.1.4

package/dist/index.d.ts

@@ -27,6 +27,48 @@ export declare const OOXML_NS: {
 };
 type OoxmlPrefix = keyof typeof OOXML_NS;
 //#endregion
+//#region src/archive.d.ts
+/** Maximum bytes any single archive entry may decompress to. */
+export declare const DOCX_MAX_ENTRY_BYTES: number;
+/** Maximum cumulative uncompressed bytes the archive may yield. */
+export declare const DOCX_MAX_TOTAL_BYTES: number;
+/**
+ * Maximum number of entries an archive may declare. Real DOCX/XLSX
+ * documents have well under 200; orders of magnitude above that
+ * indicate a hostile archive.
+ */
+export declare const DOCX_MAX_ENTRIES = 4096;
+declare const DocxArchiveError_base: import("better-result").TaggedErrorClass<"DocxArchiveError">;
+export declare class DocxArchiveError extends DocxArchiveError_base<{
+  message: string;
+  reason: "load-failed" | "too-many-entries" | "entry-too-large" | "total-too-large" | "invalid-entry-name";
+  cause?: unknown;
+}> {}
+type ArchiveOptions = {
+  maxEntryBytes?: number;
+  maxTotalBytes?: number;
+  maxEntries?: number;
+};
+type DocxArchive = {
+  /**
+   * The underlying JSZip instance. Safe for write operations
+   * (`zip.file(path, value)`, `zip.generateAsync(...)`); for reads,
+   * prefer the bounded helpers on this object.
+   */
+  zip: JSZip;
+  /**
+   * Read an entry as UTF-8 text. Returns null if the entry is not in
+   * the archive. Throws `DocxArchiveError` if the read would cross
+   * the per-entry or cumulative archive cap.
+   */
+  readEntryString: (path: string) => Promise<string | null>;
+  /** As {@link readEntryString} but returns the raw bytes. */
+  readEntryUint8: (path: string) => Promise<Uint8Array | null>;
+};
+/** Load and validate an archive, preserving the promise-based ZIP API. */
+export declare const loadDocx: (buffer: ArrayBuffer | Uint8Array | Buffer, options?: ArchiveOptions) => Promise<JSZip>;
+export declare const loadDocxArchive: (buffer: ArrayBuffer | Uint8Array | Buffer, options?: ArchiveOptions) => Promise<DocxArchive>;
+//#endregion
 //#region src/zip.d.ts
 /** Standard DOCX compression options */
 export declare const DOCX_COMPRESSION: {
@@ -36,8 +78,6 @@ export declare const DOCX_COMPRESSION: {
     level: number;
   };
 };
-/** Load a DOCX file (ArrayBuffer) into a JSZip instance */
-export declare const loadDocx: (buffer: ArrayBuffer) => Promise<JSZip>;
 /** Extract a text file from a ZIP */
 export declare const extractText: (zip: JSZip, path: string) => Promise<string | null>;
 /** Extract a binary file from a ZIP */
@@ -92,4 +132,4 @@ export declare const sanitizeAttachedTemplateRelationships: (xml: string, relati
 /** Remove WordprocessingML references to the relationships removed above. */
 export declare const sanitizeAttachedTemplateSource: (xml: string, removedRelationshipIds: readonly string[]) => SanitizedAttachedTemplateSource;
 //#endregion
-export type { AttachedTemplateRelationshipFinding, AttachedTemplateTargetKind, OoxmlPrefix };
+export type { ArchiveOptions, AttachedTemplateRelationshipFinding, AttachedTemplateTargetKind, DocxArchive, OoxmlPrefix };

package/dist/index.js

@@ -1,3 +1,4 @@
+import { Result, TaggedError } from "better-result";
 import JSZip from "jszip";
 import * as slimdom from "slimdom";
 //#region src/namespaces.ts
@@ -27,6 +28,351 @@ const OOXML_NS = {
 	pr: "http://schemas.openxmlformats.org/package/2006/relationships"
 };
 //#endregion
+//#region src/archive.ts
+/** Bounded metadata validation and sequential reads over OOXML archives. */
+/** Maximum bytes any single archive entry may decompress to. */
+const DOCX_MAX_ENTRY_BYTES = 134217728;
+/** Maximum cumulative uncompressed bytes the archive may yield. */
+const DOCX_MAX_TOTAL_BYTES = 268435456;
+/**
+* Maximum number of entries an archive may declare. Real DOCX/XLSX
+* documents have well under 200; orders of magnitude above that
+* indicate a hostile archive.
+*/
+const DOCX_MAX_ENTRIES = 4096;
+var DocxArchiveError = class extends TaggedError("DocxArchiveError") {};
+const isStreamingEntry = (entry) => "internalStream" in entry && typeof entry.internalStream === "function";
+const readEntryBounded = async (entry, { maxEntryBytes, remainingBytes, onChunk }) => await new Promise((resolve, reject) => {
+	if (!isStreamingEntry(entry)) {
+		reject(new DocxArchiveError({
+			message: "Failed to read DOCX entry",
+			reason: "load-failed"
+		}));
+		return;
+	}
+	const stream = entry.internalStream("uint8array");
+	let bytes = 0;
+	let settled = false;
+	stream.on("data", (chunk) => {
+		if (settled) return;
+		bytes += chunk.byteLength;
+		if (bytes > maxEntryBytes || bytes > remainingBytes) {
+			settled = true;
+			stream.pause();
+			reject(new DocxArchiveError({
+				message: "DOCX entry exceeds its decompression budget",
+				reason: bytes > maxEntryBytes ? "entry-too-large" : "total-too-large"
+			}));
+			return;
+		}
+		onChunk?.(chunk);
+	});
+	stream.on("error", (cause) => {
+		if (!settled) {
+			settled = true;
+			reject(new DocxArchiveError({
+				message: "Failed to read DOCX entry",
+				reason: "load-failed",
+				cause
+			}));
+		}
+	});
+	stream.on("end", () => {
+		if (!settled) {
+			settled = true;
+			resolve(bytes);
+		}
+	});
+	stream.resume();
+});
+const invalid = () => Result.err(new DocxArchiveError({
+	message: "DOCX archive contains invalid entry metadata",
+	reason: "load-failed"
+}));
+const limitError = (reason) => Result.err(new DocxArchiveError({
+	message: "DOCX archive exceeds its budget",
+	reason
+}));
+const readZip64Directory = (view, locator) => {
+	if (view.getUint32(locator, true) !== 117853008 || view.getUint32(locator + 4, true) !== 0 || view.getUint32(locator + 16, true) !== 1) return invalid();
+	const recordOffset = view.getBigUint64(locator + 8, true);
+	if (recordOffset > BigInt(locator - 56)) return invalid();
+	const record = Number(recordOffset);
+	if (record < 0 || record + 56 > view.byteLength || view.getUint32(record, true) !== 101075792 || view.getBigUint64(record + 4, true) !== 44n || record + 56 !== locator) return invalid();
+	if (view.getUint32(record + 16, true) !== 0 || view.getUint32(record + 20, true) !== 0) return invalid();
+	const zipCount = view.getBigUint64(record + 32, true);
+	const zipDiskCount = view.getBigUint64(record + 24, true);
+	const zipSize = view.getBigUint64(record + 40, true);
+	const zipStart = view.getBigUint64(record + 48, true);
+	return Result.ok({
+		count: zipCount,
+		diskCount: zipDiskCount,
+		size: zipSize,
+		start: zipStart,
+		directoryEnd: record
+	});
+};
+const readDirectory = (view) => {
+	const bytes = Buffer.from(view.buffer, view.byteOffset, view.byteLength);
+	const end = bytes.lastIndexOf(new Uint8Array([
+		80,
+		75,
+		5,
+		6
+	]));
+	if (end < Math.max(0, view.byteLength - 65535 - 22) || end > view.byteLength - 22 || end + 22 + view.getUint16(end + 20, true) !== view.byteLength) return invalid();
+	if (view.getUint16(end + 4, true) !== 0 || view.getUint16(end + 6, true) !== 0) return invalid();
+	let count = BigInt(view.getUint16(end + 10, true));
+	let diskCount = BigInt(view.getUint16(end + 8, true));
+	let size = BigInt(view.getUint32(end + 12, true));
+	let start = BigInt(view.getUint32(end + 16, true));
+	let directoryEnd = end;
+	const locator = bytes.lastIndexOf(new Uint8Array([
+		80,
+		75,
+		6,
+		7
+	]));
+	const needsZip64 = count === 65535n || diskCount === 65535n || size === 4294967295n || start === 4294967295n;
+	if (!needsZip64 && locator !== -1) return invalid();
+	if (needsZip64) {
+		if (locator === -1 || locator !== end - 20) return invalid();
+		const zip64 = readZip64Directory(view, locator);
+		if (Result.isError(zip64)) return zip64;
+		const actual = zip64.value;
+		if ([
+			[
+				count,
+				actual.count,
+				65535n
+			],
+			[
+				diskCount,
+				actual.diskCount,
+				65535n
+			],
+			[
+				size,
+				actual.size,
+				4294967295n
+			],
+			[
+				start,
+				actual.start,
+				4294967295n
+			]
+		].some(([declared, value, sentinel]) => declared !== sentinel && declared !== value)) return invalid();
+		({count, diskCount, size, start, directoryEnd} = actual);
+	}
+	if (count !== diskCount || start + size !== BigInt(directoryEnd) || start > BigInt(directoryEnd)) return invalid();
+	return Result.ok({
+		count,
+		diskCount,
+		size,
+		start,
+		directoryEnd
+	});
+};
+const readEntrySizes = ({ view, offset, extraStart, extraEndOffset }) => {
+	let declared = BigInt(view.getUint32(offset + 24, true));
+	let compressed = BigInt(view.getUint32(offset + 20, true));
+	let localOffset = BigInt(view.getUint32(offset + 42, true));
+	let extra = extraStart;
+	let zip64Seen = false;
+	while (extra < extraEndOffset) {
+		if (extra + 4 > extraEndOffset) return invalid();
+		const tag = view.getUint16(extra, true);
+		const length = view.getUint16(extra + 2, true);
+		const payload = extra + 4;
+		if (payload + length > extraEndOffset) return invalid();
+		if (tag === 1) {
+			if (zip64Seen) return invalid();
+			zip64Seen = true;
+			if (length < (declared === 4294967295n ? 8 : 0) + (compressed === 4294967295n ? 8 : 0) + (localOffset === 4294967295n ? 8 : 0)) return invalid();
+			let field = payload;
+			if (declared === 4294967295n) {
+				declared = view.getBigUint64(field, true);
+				field += 8;
+			}
+			if (compressed === 4294967295n) {
+				compressed = view.getBigUint64(field, true);
+				field += 8;
+			}
+			if (localOffset === 4294967295n) localOffset = view.getBigUint64(field, true);
+		}
+		extra = payload + length;
+	}
+	if (!zip64Seen && (declared === 4294967295n || compressed === 4294967295n || localOffset === 4294967295n)) return invalid();
+	return Result.ok({
+		declared,
+		compressed,
+		localOffset
+	});
+};
+const readEntryMetadata = ({ bytes, view, offset, start, directoryEnd }) => {
+	if (offset + 46 > directoryEnd || view.getUint32(offset, true) !== 33639248) return invalid();
+	const nameLength = view.getUint16(offset + 28, true);
+	const extraLength = view.getUint16(offset + 30, true);
+	const commentLength = view.getUint16(offset + 32, true);
+	const next = offset + 46 + nameLength + extraLength + commentLength;
+	if (next > directoryEnd || nameLength === 0 || view.getUint16(offset + 34, true) !== 0) return invalid();
+	const name = Buffer.from(bytes.subarray(offset + 46, offset + 46 + nameLength)).toString("hex");
+	const sizes = readEntrySizes({
+		view,
+		offset,
+		extraStart: offset + 46 + nameLength,
+		extraEndOffset: offset + 46 + nameLength + extraLength
+	});
+	if (Result.isError(sizes)) return sizes;
+	const { declared, compressed, localOffset } = sizes.value;
+	if (compressed > start || localOffset + 30n > start) return invalid();
+	const local = Number(localOffset);
+	if (local < 0 || local + 30 > bytes.length || view.getUint32(local, true) !== 67324752) return invalid();
+	const localNameLength = view.getUint16(local + 26, true);
+	if (localOffset + BigInt(30 + localNameLength + view.getUint16(local + 28, true)) + compressed > start || localNameLength !== nameLength || Buffer.from(bytes.subarray(local + 30, local + 30 + localNameLength)).toString("hex") !== name) return invalid();
+	const directory = bytes[offset + 46 + nameLength - 1] === 47 || Math.floor(view.getUint32(offset + 38, true) / 16) % 2 === 1;
+	return Result.ok({
+		next,
+		name,
+		declared,
+		directory
+	});
+};
+const preflightArchive = (bytes, { maxEntries, maxEntryBytes, maxTotalBytes }) => {
+	if ([
+		maxEntries,
+		maxEntryBytes,
+		maxTotalBytes
+	].some((limit) => !Number.isSafeInteger(limit) || limit < 0)) return invalid();
+	const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const metadata = readDirectory(view);
+	if (Result.isError(metadata)) return metadata;
+	const { count, start, directoryEnd } = metadata.value;
+	let offset = Number(start);
+	let records = 0;
+	let total = 0n;
+	const names = /* @__PURE__ */ new Set();
+	while (offset < directoryEnd) {
+		if (++records > maxEntries) return limitError("too-many-entries");
+		const entry = readEntryMetadata({
+			bytes,
+			view,
+			offset,
+			start,
+			directoryEnd
+		});
+		if (Result.isError(entry)) return entry;
+		const { name, declared, directory, next } = entry.value;
+		if (names.has(name)) return invalid();
+		names.add(name);
+		if (!directory) {
+			if (declared > BigInt(maxEntryBytes)) return limitError("entry-too-large");
+			total += declared;
+			if (total > BigInt(maxTotalBytes)) return limitError("total-too-large");
+		}
+		offset = next;
+	}
+	if (BigInt(records) !== count) return invalid();
+	return Result.ok();
+};
+const loadDocxResult = async (buffer, options = {}) => {
+	const maxEntryBytes = options.maxEntryBytes ?? 134217728;
+	const maxTotalBytes = options.maxTotalBytes ?? 268435456;
+	const maxEntries = options.maxEntries ?? 4096;
+	if (buffer.byteLength > 268435456) return Result.err(new DocxArchiveError({
+		message: "DOCX archive exceeds the input byte limit",
+		reason: "total-too-large"
+	}));
+	const bytes = buffer instanceof ArrayBuffer ? new Uint8Array(buffer) : buffer;
+	const preflight = preflightArchive(bytes, {
+		maxEntries,
+		maxEntryBytes,
+		maxTotalBytes
+	});
+	if (Result.isError(preflight)) return preflight;
+	const loaded = await Result.tryPromise({
+		try: async () => await JSZip.loadAsync(buffer),
+		catch: (cause) => new DocxArchiveError({
+			message: "Failed to parse DOCX archive",
+			reason: "load-failed",
+			cause
+		})
+	});
+	if (Result.isError(loaded)) return loaded;
+	const zip = loaded.value;
+	for (const entry of Object.values(zip.files)) {
+		if (entry.dir) continue;
+		const originalName = entry.unsafeOriginalName ?? entry.name;
+		if (originalName.startsWith("/") || /^[a-z]:/iu.test(originalName) || originalName.includes("\\") || originalName.split("/").includes("..")) return Result.err(new DocxArchiveError({
+			message: "DOCX archive contains an invalid entry name",
+			reason: "invalid-entry-name"
+		}));
+	}
+	let validatedBytes = 0;
+	for (const entry of Object.values(zip.files)) {
+		if (entry.dir) continue;
+		const remainingBytes = maxTotalBytes - validatedBytes;
+		const read = await Result.tryPromise({
+			try: async () => await readEntryBounded(entry, {
+				maxEntryBytes,
+				remainingBytes
+			}),
+			catch: (cause) => cause instanceof DocxArchiveError ? cause : new DocxArchiveError({
+				message: "Failed to read DOCX entry",
+				reason: "load-failed",
+				cause
+			})
+		});
+		if (Result.isError(read)) return read;
+		validatedBytes += read.value;
+	}
+	return Result.ok(zip);
+};
+/** Load and validate an archive, preserving the promise-based ZIP API. */
+const loadDocx = async (buffer, options = {}) => {
+	const result = await loadDocxResult(buffer, options);
+	if (Result.isError(result)) return await Promise.reject(result.error);
+	return result.value;
+};
+const loadDocxArchive = async (buffer, options = {}) => {
+	const maxEntryBytes = options.maxEntryBytes ?? 134217728;
+	const maxTotalBytes = options.maxTotalBytes ?? 268435456;
+	const zip = await loadDocx(buffer, options);
+	let totalRead = 0;
+	let readChain = Promise.resolve();
+	const readEntry = async (path) => {
+		const work = async () => {
+			const entry = zip.file(path);
+			if (!entry) return null;
+			const remaining = maxTotalBytes - totalRead;
+			const chunks = [];
+			const size = await readEntryBounded(entry, {
+				maxEntryBytes,
+				remainingBytes: remaining,
+				onChunk: (chunk) => {
+					chunks.push(chunk);
+				}
+			});
+			totalRead += size;
+			return Buffer.concat(chunks, size);
+		};
+		const next = readChain.then(work, work);
+		readChain = next.then(() => void 0, () => void 0);
+		return await next;
+	};
+	return {
+		zip,
+		async readEntryString(path) {
+			const buf = await readEntry(path);
+			return buf === null ? null : buf.toString("utf-8");
+		},
+		async readEntryUint8(path) {
+			const buf = await readEntry(path);
+			return buf === null ? null : new Uint8Array(buf);
+		}
+	};
+};
+//#endregion
 //#region src/zip.ts
 /** Standard DOCX compression options */
 const DOCX_COMPRESSION = {
@@ -34,8 +380,6 @@ const DOCX_COMPRESSION = {
 	compression: "DEFLATE",
 	compressionOptions: { level: 6 }
 };
-/** Load a DOCX file (ArrayBuffer) into a JSZip instance */
-const loadDocx = async (buffer) => await JSZip.loadAsync(buffer);
 /** Extract a text file from a ZIP */
 const extractText = async (zip, path) => {
 	const file = zip.file(path);
@@ -58,15 +402,24 @@ const repackZip = async (zip) => await zip.generateAsync(DOCX_COMPRESSION);
 * entities produced for the other characters.
 */
 const escapeXmlAttribute = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;");
+const relationshipIds = (relsXml) => {
+	const document = slimdom.parseXmlDocument(relsXml);
+	const ids = /* @__PURE__ */ new Set();
+	for (const element of document.getElementsByTagNameNS("*", "Relationship")) {
+		const id = element.getAttribute("Id");
+		if (id !== null) ids.add(id);
+	}
+	return ids;
+};
 /** Find the next available rId in a relationships XML string */
 const findNextRId = (relsXml) => {
-	const matches = relsXml.matchAll(/Id="rId(?<num>\d+)"/gu);
-	let max = 0;
-	for (const m of matches) {
-		const n = Number.parseInt(m.groups?.["num"] ?? "0", 10);
+	let max = 0n;
+	for (const id of relationshipIds(relsXml)) {
+		if (!/^rId\d+$/u.test(id)) continue;
+		const n = BigInt(id.slice(3));
 		if (n > max) max = n;
 	}
-	return `rId${max + 1}`;
+	return `rId${max + 1n}`;
 };
 /** Ensure a content type entry exists in [Content_Types].xml */
 const ensureContentType = (contentTypesXml, partName, contentType) => {
@@ -78,7 +431,7 @@ const ensureContentType = (contentTypesXml, partName, contentType) => {
 /** Ensure a relationship entry exists */
 const ensureRelationship = (relsXml, rId, type, target) => {
 	const escapedRId = escapeXmlAttribute(rId);
-	if (relsXml.includes(`Id="${escapedRId}"`)) return relsXml;
+	if (relationshipIds(relsXml).has(rId)) return relsXml;
 	const rel = `<Relationship Id="${escapedRId}" Type="${escapeXmlAttribute(type)}" Target="${escapeXmlAttribute(target)}"/>`;
 	return relsXml.replace("</Relationships>", () => `${rel}\n</Relationships>`);
 };
@@ -206,4 +559,4 @@ const sanitizeAttachedTemplateSource = (xml, removedRelationshipIds) => {
 	};
 };
 //#endregion
-export { ATTACHED_TEMPLATE_SECURITY_RULE, ATTACHED_TEMPLATE_TARGET_KIND, DOCX_COMPRESSION, OOXML_NS, classifyAttachedTemplateTarget, ensureContentType, ensureRelationship, extractBinary, extractText, findNextRId, isOpcRelationshipPartPath, loadDocx, relationshipSourcePartPath, repackZip, sanitizeAttachedTemplateRelationships, sanitizeAttachedTemplateSource };
+export { ATTACHED_TEMPLATE_SECURITY_RULE, ATTACHED_TEMPLATE_TARGET_KIND, DOCX_COMPRESSION, DOCX_MAX_ENTRIES, DOCX_MAX_ENTRY_BYTES, DOCX_MAX_TOTAL_BYTES, DocxArchiveError, OOXML_NS, classifyAttachedTemplateTarget, ensureContentType, ensureRelationship, extractBinary, extractText, findNextRId, isOpcRelationshipPartPath, loadDocx, loadDocxArchive, relationshipSourcePartPath, repackZip, sanitizeAttachedTemplateRelationships, sanitizeAttachedTemplateSource };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stll/docx-utils",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Low-level helpers for reading and writing DOCX/OOXML zip packages: text and binary extraction, relationship and content-type management, and namespace constants.",
   "keywords": [
     "docx",
@@ -41,18 +41,22 @@
     "pack:dry-run": "bun pm pack --dry-run",
     "test": "bun test src",
     "typecheck": "bun ../../packages/scripts/src/tsc-native.ts --noEmit",
-    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --deny-warnings --type-aware packages/docx-utils",
+    "lint": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --report-unused-disable-directives-severity=error --type-aware --type-check packages/docx-utils",
     "lint:fix": "cd ../.. && bun --bun oxlint -c oxlint.config.ts --type-aware --fix packages/docx-utils",
     "format": "bun ../../scripts/run-oxfmt.ts .",
-    "prepack": "bun run build"
+    "prepack": "bun run build",
+    "test:property": "bun test --preload @stll/property-testing/preload $(grep -rlF 'fc.assert' src --include='*.test.ts')"
   },
   "dependencies": {
-    "jszip": "3.10.1",
+    "better-result": "3.0.1",
+    "jszip": "3.10.2",
     "slimdom": "^4.3.5"
   },
   "devDependencies": {
+    "@stll/property-testing": "0.0.0",
     "@stll/typescript-config": "0.0.0",
     "bun-types": "1.4.2",
+    "fast-check": "^4.10.1",
     "tsdown": "0.23.0"
   },
   "main": "./dist/index.js",