@stll/docx-utils 0.2.0 → 0.3.0

package/README.md

@@ -1,17 +1,12 @@
 # @stll/docx-utils
 
-Low-level helpers for reading and writing DOCX/OOXML zip packages.
-
-The package wraps the mechanical parts of working with a DOCX file: loading and
-repacking the underlying zip, extracting text or binary parts, managing
-relationships and content types, and the OOXML namespace constants those
-operations need.
+Low-level helpers for OOXML packages: relationships and content types,
+attached-template handling, office format metadata, and the namespace
+constants those operations need. Load bounded archives with `loadDocx` or
+`loadDocxArchive`; write archives with `@stll/docx-core/zip`.
 
 ```ts
-import { loadDocx, extractText, ensureRelationship } from "@stll/docx-utils";
-
-const zip = await loadDocx(bytes);
-const text = await extractText(zip, "word/document.xml");
+import { ensureRelationship, OOXML_NS } from "@stll/docx-utils";
 ```
 
 ## Install
@@ -23,10 +18,13 @@ bun add @stll/docx-utils
 ## Exports
 
 - `OOXML_NS` / `OoxmlPrefix` — OOXML namespace constants and prefixes.
-- `loadDocx`, `repackZip`, `extractText`, `extractBinary`, `DOCX_COMPRESSION` —
-  zip-level read and write helpers.
 - `findNextRId`, `ensureContentType`, `ensureRelationship` — relationship and
   content-type management.
+- `classifyAttachedTemplateTarget`, `sanitizeAttachedTemplateRelationships`,
+  `sanitizeAttachedTemplateSource` — attached-template handling.
+
+- `loadDocx`, `loadDocxArchive`, `DocxArchiveError` — shared bounded archive reads.
+- `DOCX_MAX_ENTRIES`, `DOCX_MAX_ENTRY_BYTES`, `DOCX_MAX_TOTAL_BYTES` — archive limits.
 
 ## License
 

package/dist/index.d.ts

@@ -1,5 +1,4 @@
-import JSZip from "jszip";
-//#region src/namespaces.d.ts
+import { ZipArchive } from "@stll/docx-core/zip";
 /**
  * Common OOXML namespace URIs.
  *
@@ -26,86 +25,12 @@ export declare const OOXML_NS: {
   readonly pr: "http://schemas.openxmlformats.org/package/2006/relationships";
 };
 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. Write entries with `writeZipEntry`
-   * and repack with `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: {
-  type: "arraybuffer";
-  compression: "DEFLATE";
-  compressionOptions: {
-    level: number;
-  };
-};
-/** 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 */
-export declare const extractBinary: (zip: JSZip, path: string) => Promise<ArrayBuffer | null>;
-/** Repack a ZIP to ArrayBuffer with standard DOCX compression */
-export declare const repackZip: (zip: JSZip) => Promise<ArrayBuffer>;
-//#endregion
-//#region src/zip-entry.d.ts
-/** Text or bytes to store as one archive entry. */
-type ZipEntryContent = string | Uint8Array | ArrayBuffer;
-/**
- * Write `content` to `path` in `zip`. Text is UTF-8 encoded here, in one
- * pass over the whole string, before JSZip sees it: JSZip encodes string
- * input in 16 KiB pieces, which splits a surrogate pair that straddles a
- * piece boundary into two U+FFFD characters. Returns `zip`, like
- * `JSZip#file`, so writes can be chained.
- */
-export declare const writeZipEntry: (zip: JSZip, path: string, content: ZipEntryContent, options?: JSZip.JSZipFileOptions) => JSZip;
-//#endregion
-//#region src/relationships.d.ts
 /** Find the next available rId in a relationships XML string */
 export declare const findNextRId: (relsXml: string) => string;
 /** Ensure a content type entry exists in [Content_Types].xml */
 export declare const ensureContentType: (contentTypesXml: string, partName: string, contentType: string) => string;
 /** Ensure a relationship entry exists */
 export declare const ensureRelationship: (relsXml: string, rId: string, type: string, target: string) => string;
-//#endregion
-//#region src/attached-template.d.ts
 export declare const ATTACHED_TEMPLATE_SECURITY_RULE: "ooxml_attached_template";
 export declare const ATTACHED_TEMPLATE_TARGET_KIND: {
   readonly local: "local";
@@ -143,5 +68,44 @@ export declare const isOpcRelationshipPartPath: (path: string) => boolean;
 export declare const sanitizeAttachedTemplateRelationships: (xml: string, relationshipsPartPath: string) => SanitizedAttachedTemplateRelationships;
 /** Remove WordprocessingML references to the relationships removed above. */
 export declare const sanitizeAttachedTemplateSource: (xml: string, removedRelationshipIds: readonly string[]) => SanitizedAttachedTemplateSource;
-//#endregion
-export type { ArchiveOptions, AttachedTemplateRelationshipFinding, AttachedTemplateTargetKind, DocxArchive, OoxmlPrefix, ZipEntryContent };
+/** 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" | "compression-ratio-exceeded" | "invalid-entry-name";
+  cause?: unknown;
+}> {}
+type ArchiveOptions = {
+  maxEntryBytes?: number;
+  maxTotalBytes?: number;
+  maxEntries?: number;
+};
+type DocxArchive = {
+  /** The archive. Entry reads stay within its declared sizes. */
+  zip: ZipArchive;
+  /**
+   * 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 cumulative archive cap.
+   */
+  readEntryString: (path: string) => Promise<string | null>;
+  /** As {@link readEntryString} but returns the raw bytes. */
+  readEntryUint8: (path: string) => Promise<Uint8Array | null>;
+};
+/** Load a bounded archive through the shared promise-based contract. */
+export declare const loadDocx: (buffer: ArrayBuffer | Uint8Array, options?: ArchiveOptions) => Promise<ZipArchive>;
+/**
+ * Open an archive with {@link loadDocx} and read entries through a running
+ * total, so repeated reads stay within `maxTotalBytes` too.
+ */
+export declare const loadDocxArchive: (buffer: ArrayBuffer | Uint8Array, options?: ArchiveOptions) => Promise<DocxArchive>;
+export type { ArchiveOptions, AttachedTemplateRelationshipFinding, AttachedTemplateTargetKind, DocxArchive, OoxmlPrefix };

package/dist/index.js

@@ -1,7 +1,7 @@
-import { Result, TaggedError } from "better-result";
-import JSZip from "jszip";
 import * as slimdom from "slimdom";
-//#region src/namespaces.ts
+import { Result, TaggedError } from "better-result";
+import { ZipArchive, ZipError } from "@stll/docx-core/zip";
+// src/namespaces.ts
 /**
 * Common OOXML namespace URIs.
 *
@@ -27,389 +27,7 @@ const OOXML_NS = {
 	ct: "http://schemas.openxmlformats.org/package/2006/content-types",
 	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 = {
-	type: "arraybuffer",
-	compression: "DEFLATE",
-	compressionOptions: { level: 6 }
-};
-/** Extract a text file from a ZIP */
-const extractText = async (zip, path) => {
-	const file = zip.file(path);
-	if (!file) return null;
-	return await file.async("string");
-};
-/** Extract a binary file from a ZIP */
-const extractBinary = async (zip, path) => {
-	const file = zip.file(path);
-	if (!file) return null;
-	return await file.async("arraybuffer");
-};
-/** Repack a ZIP to ArrayBuffer with standard DOCX compression */
-const repackZip = async (zip) => await zip.generateAsync(DOCX_COMPRESSION);
-//#endregion
-//#region src/zip-entry.ts
-const utf8 = new TextEncoder();
-/**
-* Write `content` to `path` in `zip`. Text is UTF-8 encoded here, in one
-* pass over the whole string, before JSZip sees it: JSZip encodes string
-* input in 16 KiB pieces, which splits a surrogate pair that straddles a
-* piece boundary into two U+FFFD characters. Returns `zip`, like
-* `JSZip#file`, so writes can be chained.
-*/
-const writeZipEntry = (zip, path, content, options) => {
-	const data = typeof content === "string" ? utf8.encode(content) : content;
-	return zip.file(path, data, options);
-};
-//#endregion
-//#region src/relationships.ts
+// src/relationships.ts
 /**
 * Escape a string for safe use inside a double-quoted XML attribute value.
 * Order matters: `&` must be escaped first so it does not double-escape the
@@ -449,8 +67,7 @@ const ensureRelationship = (relsXml, rId, type, target) => {
 	const rel = `<Relationship Id="${escapedRId}" Type="${escapeXmlAttribute(type)}" Target="${escapeXmlAttribute(target)}"/>`;
 	return relsXml.replace("</Relationships>", () => `${rel}\n</Relationships>`);
 };
-//#endregion
-//#region src/attached-template.ts
+// src/attached-template.ts
 const ATTACHED_TEMPLATE_SECURITY_RULE = "ooxml_attached_template";
 const ATTACHED_TEMPLATE_TARGET_KIND = {
 	local: "local",
@@ -572,5 +189,148 @@ const sanitizeAttachedTemplateSource = (xml, removedRelationshipIds) => {
 		xml: slimdom.serializeToWellFormedString(document)
 	};
 };
-//#endregion
-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, writeZipEntry };
+// src/archive.ts
+/**
+* Bounded reads of OOXML archives (DOCX, XLSX, PPTX) for OOXML consumers.
+*
+* `ZipArchive.read` checks every size, name and record an archive declares
+* before anything inflates, and each entry inflates no further than its
+* declared size. The limits here are the shared owner's policy on top of that.
+*/
+/** 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;
+/**
+* Inflated bytes allowed per compressed byte for a markup entry, and for the
+* archive as a whole, once either passes 4 MiB. Binary parts (an uncompressed
+* bitmap of one colour) can legitimately compress further; the byte limits
+* bound them.
+*/
+const MAX_MARKUP_COMPRESSION_RATIO = 200;
+const COMPRESSION_RATIO_GRACE_BYTES = 4194304;
+const MARKUP_EXTENSIONS = /* @__PURE__ */ new Set([
+	"xml",
+	"rels",
+	"vml",
+	"txt",
+	"htm",
+	"html"
+]);
+var DocxArchiveError = class extends TaggedError("DocxArchiveError") {};
+const REASONS = {
+	malformed: "load-failed",
+	unsupported: "load-failed",
+	"duplicate-entry": "load-failed",
+	"corrupt-entry": "load-failed",
+	"invalid-entry-name": "invalid-entry-name",
+	"too-many-entries": "too-many-entries",
+	"entry-too-large": "entry-too-large",
+	"declared-size-exceeded": "entry-too-large",
+	"total-too-large": "total-too-large",
+	"compression-ratio": "compression-ratio-exceeded"
+};
+const toArchiveError = (cause) => cause instanceof DocxArchiveError ? cause : new DocxArchiveError({
+	message: cause instanceof ZipError ? cause.message : "Failed to parse DOCX archive",
+	reason: cause instanceof ZipError ? REASONS[cause.reason] : "load-failed",
+	cause
+});
+const isMarkup = (path) => MARKUP_EXTENSIONS.has(path.slice(path.lastIndexOf(".") + 1).toLowerCase());
+/** Load a bounded archive through the shared promise-based contract. */
+const loadDocx = async (buffer, options = {}) => {
+	const result = await loadDocxResult(buffer, options);
+	return Result.isError(result) ? await Promise.reject(result.error) : result.value;
+};
+/**
+* Open an archive within the shared limits and inflate every entry once, so
+* a corrupt or mis-declared entry is refused here rather than at a later
+* read. Rejects with `DocxArchiveError`.
+*/
+const loadDocxResult = async (buffer, options = {}) => {
+	const maxTotalBytes = options.maxTotalBytes ?? 268435456;
+	const maxEntryBytes = options.maxEntryBytes ?? 134217728;
+	const maxEntries = options.maxEntries ?? 4096;
+	if ([
+		maxEntries,
+		maxEntryBytes,
+		maxTotalBytes
+	].some((limit) => !Number.isSafeInteger(limit) || limit < 0)) return Result.err(new DocxArchiveError({
+		message: "DOCX archive contains invalid entry metadata",
+		reason: "load-failed"
+	}));
+	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 view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+	const earliest = Math.max(0, bytes.length - 65535 - 22);
+	const trailer = bytes.subarray(earliest);
+	const marker = trailer.findLastIndex((byte, index) => byte === 80 && trailer[index + 1] === 75 && trailer[index + 2] === 5 && trailer[index + 3] === 6);
+	const end = earliest + marker;
+	if (marker === -1 || end > bytes.length - 22 || end + 22 + view.getUint16(end + 20, true) !== bytes.length) return Result.err(new DocxArchiveError({
+		message: "DOCX archive contains invalid entry metadata",
+		reason: "load-failed"
+	}));
+	return await Result.tryPromise({
+		try: async () => {
+			const zip = await ZipArchive.read(buffer, {
+				limits: {
+					maxEntries,
+					maxEntryBytes,
+					maxTotalBytes,
+					maxCompressionRatio: MAX_MARKUP_COMPRESSION_RATIO,
+					compressionRatioGraceBytes: COMPRESSION_RATIO_GRACE_BYTES
+				},
+				isCompressionRatioExempt: (path) => !isMarkup(path)
+			});
+			for (const entry of zip.entries()) await entry.bytes();
+			return zip;
+		},
+		catch: toArchiveError
+	});
+};
+/**
+* Open an archive with {@link loadDocx} and read entries through a running
+* total, so repeated reads stay within `maxTotalBytes` too.
+*/
+const loadDocxArchive = async (buffer, options = {}) => {
+	const maxTotalBytes = options.maxTotalBytes ?? 268435456;
+	const maxEntryBytes = options.maxEntryBytes ?? 134217728;
+	const zip = await loadDocx(buffer, options);
+	let totalRead = 0;
+	const readEntry = async (path) => {
+		const entry = zip.entry(path);
+		if (!entry) return null;
+		if (entry.size > maxEntryBytes || totalRead + entry.size > maxTotalBytes) return await Promise.reject(new DocxArchiveError({
+			message: "DOCX entry exceeds its decompression budget",
+			reason: entry.size > maxEntryBytes ? "entry-too-large" : "total-too-large"
+		}));
+		const reservedBytes = entry.size;
+		totalRead += reservedBytes;
+		const bytes = await Result.tryPromise({
+			try: async () => await entry.bytes(),
+			catch: toArchiveError
+		});
+		if (Result.isError(bytes)) {
+			totalRead -= reservedBytes;
+			return await Promise.reject(bytes.error);
+		}
+		return bytes.value;
+	};
+	return {
+		zip,
+		async readEntryString(path) {
+			const bytes = await readEntry(path);
+			return bytes === null ? null : new TextDecoder("utf-8", { ignoreBOM: true }).decode(bytes);
+		},
+		readEntryUint8: readEntry
+	};
+};
+export { ATTACHED_TEMPLATE_SECURITY_RULE, ATTACHED_TEMPLATE_TARGET_KIND, DOCX_MAX_ENTRIES, DOCX_MAX_ENTRY_BYTES, DOCX_MAX_TOTAL_BYTES, DocxArchiveError, OOXML_NS, classifyAttachedTemplateTarget, ensureContentType, ensureRelationship, findNextRId, isOpcRelationshipPartPath, loadDocx, loadDocxArchive, relationshipSourcePartPath, sanitizeAttachedTemplateRelationships, sanitizeAttachedTemplateSource };

package/dist/office-formats.d.ts

@@ -1,4 +1,3 @@
-//#region src/office-formats.d.ts
 /** ZIP-based office formats; legacy binary formats are not XML containers. */
 export declare const OFFICE_ARCHIVE_FORMATS: {
   readonly docx: {
@@ -85,5 +84,4 @@ export declare const OFFICE_ARCHIVE_FORMATS: {
     readonly family: "odf";
     readonly mimeType: "application/vnd.oasis.opendocument.presentation-template";
   };
-};
-//#endregion
+};

package/dist/office-formats.js

@@ -1,4 +1,4 @@
-//#region src/office-formats.ts
+// src/office-formats.ts
 /** ZIP-based office formats; legacy binary formats are not XML containers. */
 const OFFICE_ARCHIVE_FORMATS = {
 	docx: {
@@ -86,5 +86,4 @@ const OFFICE_ARCHIVE_FORMATS = {
 		mimeType: "application/vnd.oasis.opendocument.presentation-template"
 	}
 };
-//#endregion
 export { OFFICE_ARCHIVE_FORMATS };

package/dist/office-metadata.d.ts

@@ -1,5 +1,4 @@
 import { Attr, Document, Element } from "slimdom";
-//#region src/office-metadata.d.ts
 export declare const officeIdentityAttributePolicy: (name: string) => {
   readonly type: "replace";
   readonly replacement: "Author";
@@ -34,5 +33,4 @@ export type OfficeIdentityField = {
   field: string;
 };
 /** Internal reference IDs and document/comment body text are deliberately excluded. */
-export declare const officeIdentityFields: (document: Document, part: string) => OfficeIdentityField[];
-//#endregion
+export declare const officeIdentityFields: (document: Document, part: string) => OfficeIdentityField[];

package/dist/office-metadata.js

@@ -1,4 +1,4 @@
-//#region src/office-metadata.ts
+// src/office-metadata.ts
 const PROPERTY_FIELDS = /* @__PURE__ */ new Set([
 	"creator",
 	"lastmodifiedby",
@@ -84,5 +84,4 @@ const officeIdentityFields = (document, part) => {
 	}
 	return result;
 };
-//#endregion
 export { isOfficeCollaborationPart, isOfficeIdentityPart, officeIdentityAttributePolicy, officeIdentityFields };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stll/docx-utils",
-  "version": "0.2.0",
-  "description": "Low-level helpers for reading and writing DOCX/OOXML zip packages: text and binary extraction, relationship and content-type management, and namespace constants.",
+  "version": "0.3.0",
+  "description": "Low-level OOXML helpers: relationship and content-type management, attached-template handling, office format metadata, and namespace constants.",
   "keywords": [
     "docx",
     "ooxml",
@@ -53,21 +53,21 @@
     "typecheck": "bun check --no-pretty --all --project=tsconfig.json",
     "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",
     "test:property": "bun test --preload @stll/property-testing/preload $(grep -rlE 'fc\\.assert|assertProperty' src --include='*.test.ts')"
   },
   "dependencies": {
+    "@stll/docx-core": "0.41.0",
     "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.3",
+    "bun-types": "1.4.4",
     "fast-check": "^4.10.2",
-    "tsdown": "0.23.0"
+    "tsdown": "0.23.4",
+    "tsrs": "0.20.1-ts7.1.0-beta"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts"