@stll/folio-core 0.3.1 → 0.4.0

package/dist/ai-edits/headless.d.ts

@@ -5,7 +5,8 @@ import { FolioReviewChange, FolioReviewChangeKind } from "./read.js";
 //#region src/ai-edits/headless.d.ts
 /** Options for {@link FolioDocxReviewer.fromBuffer}. */
 type FolioDocxReviewerOptions = {
-  /** Default author for tracked changes and comments. (default: `"AI"`) */author?: string;
+  /** Default author for tracked changes and comments. (default: `"AI"`) */author?: string; /** Password for Agile-encrypted .docx files (Office 2010+). */
+  password?: string | undefined;
 };
 /** Options for {@link FolioDocxReviewer.applyOperations}. */
 type FolioApplyOperationsOptions = {

package/dist/ai-edits/headless.js

@@ -181,17 +181,19 @@ var FolioDocxReviewer = class FolioDocxReviewer {
 	static async fromBuffer(buffer, options = {}) {
 		const baseDocument = await parseDocx(buffer, {
 			detectVariables: false,
-			preloadFonts: false
+			preloadFonts: false,
+			password: options.password
 		});
 		const plugins = singletonManager.getPlugins();
+		const state = ensureDeterministicParaIdsInState(EditorState.create({
+			schema,
+			doc: toProseDoc(baseDocument),
+			plugins
+		}));
 		return new FolioDocxReviewer({
 			baseDocument,
-			originalBuffer: buffer,
-			state: ensureDeterministicParaIdsInState(EditorState.create({
-				schema,
-				doc: toProseDoc(baseDocument),
-				plugins
-			})),
+			originalBuffer: baseDocument.originalBuffer ?? buffer,
+			state,
 			author: options.author ?? "AI"
 		});
 	}

package/dist/controller/layoutPipeline.js

@@ -96,6 +96,15 @@ function runLayoutPipeline(deps, state, options = {}) {
 			firstPageHeaderContent: firstPageHeaderForRender,
 			firstPageFooterContent: firstPageFooterForRender
 		};
+		const buildSectionHfExtenderContent = () => {
+			if (!sectionHeaderFooterRefs) return;
+			return sectionHeaderFooterRefs.map((refs) => ({
+				headerContent: pickSectionHeaderFooterContent(headerContentByRId, refs.headerDefault, refs.evenAndOddHeaders === true ? refs.headerEven : void 0),
+				footerContent: pickSectionHeaderFooterContent(footerContentByRId, refs.footerDefault, refs.evenAndOddHeaders === true ? refs.footerEven : void 0),
+				firstPageHeaderContent: refs.titlePg === true ? headerContentByRId?.get(refs.headerFirst ?? "") : void 0,
+				firstPageFooterContent: refs.titlePg === true ? footerContentByRId?.get(refs.footerFirst ?? "") : void 0
+			}));
+		};
 		const hfWarn = (msg) => {
 			console.warn(`[PagedEditor] ${msg}`);
 		};
@@ -128,6 +137,7 @@ function runLayoutPipeline(deps, state, options = {}) {
 			restoreSectionBreakMargins();
 			extendSectionBreakMargins(sectionBreaks, {
 				content,
+				sectionContent: buildSectionHfExtenderContent(),
 				bodyPageSize: pageSize,
 				bodyMargins,
 				warn: hfWarn
@@ -402,5 +412,17 @@ function runLayoutPipeline(deps, state, options = {}) {
 	syncCoordinator.onLayoutComplete(currentEpoch);
 	return outcome;
 }
+function pickSectionHeaderFooterContent(byRId, defaultRId, evenRId) {
+	const defaultContent = defaultRId ? byRId?.get(defaultRId) : void 0;
+	const evenContent = evenRId ? byRId?.get(evenRId) : void 0;
+	if (!defaultContent) return evenContent;
+	if (!evenContent) return defaultContent;
+	return headerFooterMarginPushHeight(evenContent) > headerFooterMarginPushHeight(defaultContent) ? evenContent : defaultContent;
+}
+function headerFooterMarginPushHeight(content) {
+	const bottom = content.marginPushBottom ?? content.visualBottom ?? content.height;
+	const top = content.marginPushTop ?? content.visualTop ?? 0;
+	return Math.max(bottom - top, content.height);
+}
 //#endregion
 export { runLayoutPipeline };

package/dist/docx/encryption/agileDecryption.d.ts

@@ -0,0 +1,6 @@
+import { AgileKeyMaterial } from "./encryptionInfo.js";
+
+//#region src/docx/encryption/agileDecryption.d.ts
+declare const decryptAgileEncryptedPackage: (password: string, material: AgileKeyMaterial, encryptedPackage: Uint8Array) => Promise<Uint8Array>;
+//#endregion
+export { decryptAgileEncryptedPackage };

package/dist/docx/encryption/agileDecryption.js

@@ -0,0 +1,208 @@
+import { bytesEqual, joinBytes, padToBlock, passwordToUtf16Le, toArrayBuffer, writeUint32Le } from "./cryptoBytes.js";
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError } from "./errors.js";
+//#region src/docx/encryption/agileDecryption.ts
+/**
+* Agile Encryption decryption (Office 2010+) using Web Crypto.
+*
+* Algorithm steps follow [MS-OFFCRYPTO] sections 2.3.4.9 through 2.3.4.15.
+*
+* @see https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offcrypto/
+*/
+/** [MS-OFFCRYPTO] 2.3.4.15 — block keys used during password verification. */
+const PASSWORD_INPUT_BLOCK_KEY = new Uint8Array([
+	254,
+	167,
+	210,
+	118,
+	59,
+	75,
+	158,
+	121
+]);
+const PASSWORD_DIGEST_BLOCK_KEY = new Uint8Array([
+	215,
+	170,
+	15,
+	109,
+	48,
+	97,
+	52,
+	78
+]);
+const INTERMEDIATE_KEY_BLOCK_KEY = new Uint8Array([
+	20,
+	110,
+	11,
+	231,
+	171,
+	172,
+	208,
+	214
+]);
+const INTEGRITY_KEY_BLOCK_KEY = new Uint8Array([
+	95,
+	178,
+	173,
+	1,
+	12,
+	185,
+	225,
+	246
+]);
+const INTEGRITY_DIGEST_BLOCK_KEY = new Uint8Array([
+	160,
+	103,
+	127,
+	2,
+	178,
+	44,
+	132,
+	51
+]);
+const PACKAGE_PLAINTEXT_SIZE_BYTES = 8;
+const PACKAGE_SEGMENT_BYTES = 4096;
+const subtleCrypto = () => {
+	const crypto = globalThis.crypto?.subtle;
+	if (!crypto) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "Web Crypto API (SubtleCrypto) is not available in this environment"
+	});
+	return crypto;
+};
+const webHashName = (officeName) => {
+	const resolved = {
+		SHA1: "SHA-1",
+		"SHA-1": "SHA-1",
+		SHA256: "SHA-256",
+		"SHA-256": "SHA-256",
+		SHA384: "SHA-384",
+		"SHA-384": "SHA-384",
+		SHA512: "SHA-512",
+		"SHA-512": "SHA-512"
+	}[officeName];
+	if (!resolved) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: `Unsupported hash algorithm: ${officeName}`
+	});
+	return resolved;
+};
+const digest = async (algorithm, input) => {
+	const output = await subtleCrypto().digest(algorithm, toArrayBuffer(input));
+	return new Uint8Array(output);
+};
+const importAesKey = (rawKey, usages) => subtleCrypto().importKey("raw", toArrayBuffer(rawKey), { name: "AES-CBC" }, false, usages);
+const decryptAesCbc = async (rawKey, iv, ciphertext) => {
+	const blockSize = 16;
+	if (ciphertext.length === 0 || ciphertext.length % blockSize !== 0) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "AES ciphertext length must be a positive multiple of the block size"
+	});
+	const subtle = subtleCrypto();
+	const key = await importAesKey(rawKey, ["encrypt", "decrypt"]);
+	const lastBlock = ciphertext.subarray(ciphertext.length - blockSize);
+	const pkcs7PadPlaintext = new Uint8Array(blockSize);
+	pkcs7PadPlaintext.fill(blockSize);
+	const syntheticPadding = new Uint8Array(await subtle.encrypt({
+		name: "AES-CBC",
+		iv: toArrayBuffer(lastBlock)
+	}, key, pkcs7PadPlaintext)).subarray(0, blockSize);
+	const paddedCiphertext = new Uint8Array(ciphertext.length + blockSize);
+	paddedCiphertext.set(ciphertext);
+	paddedCiphertext.set(syntheticPadding, ciphertext.length);
+	const decrypted = await subtle.decrypt({
+		name: "AES-CBC",
+		iv: toArrayBuffer(iv)
+	}, key, toArrayBuffer(paddedCiphertext));
+	return new Uint8Array(decrypted).subarray(0, ciphertext.length);
+};
+/** [MS-OFFCRYPTO] 2.3.4.9 — iterated hash of password + salt. */
+const hashPassword = async (password, salt, iterations, hashName) => {
+	const algorithm = webHashName(hashName);
+	let state = await digest(algorithm, joinBytes([salt, passwordToUtf16Le(password)]));
+	for (let i = 0; i < iterations; i++) state = await digest(algorithm, joinBytes([writeUint32Le(i), state]));
+	return state;
+};
+/** [MS-OFFCRYPTO] 2.3.4.9 — finalize a derived key with a block key suffix. */
+const finalizeDerivedKey = async (passwordHash, blockKey, hashName, keyBits) => {
+	return (await digest(webHashName(hashName), joinBytes([passwordHash, blockKey]))).subarray(0, keyBits / 8);
+};
+const segmentIv = async (packageSalt, segmentIndex, hashName, blockBytes) => {
+	return (await digest(webHashName(hashName), joinBytes([packageSalt, writeUint32Le(segmentIndex)]))).subarray(0, blockBytes);
+};
+const integrityIv = async (packageSalt, blockKey, hashName, blockBytes) => {
+	return (await digest(webHashName(hashName), joinBytes([packageSalt, blockKey]))).subarray(0, blockBytes);
+};
+const unlockIntermediateKey = async (password, material) => {
+	const passwordHash = await hashPassword(password, material.passwordSalt, material.passwordIterations, material.passwordHash);
+	const verifierKey = await finalizeDerivedKey(passwordHash, PASSWORD_INPUT_BLOCK_KEY, material.passwordHash, material.passwordKeyBits);
+	const digestKey = await finalizeDerivedKey(passwordHash, PASSWORD_DIGEST_BLOCK_KEY, material.passwordHash, material.passwordKeyBits);
+	const intermediateKey = await finalizeDerivedKey(passwordHash, INTERMEDIATE_KEY_BLOCK_KEY, material.passwordHash, material.passwordKeyBits);
+	const verifierIv = padToBlock(material.passwordSalt, material.passwordBlockBytes);
+	const verifierPlaintext = await decryptAesCbc(verifierKey, verifierIv, material.encryptedVerifierInput);
+	const digestPlaintext = await decryptAesCbc(digestKey, verifierIv, material.encryptedVerifierDigest);
+	const actualDigest = await digest(webHashName(material.passwordHash), verifierPlaintext);
+	if (!bytesEqual(actualDigest, digestPlaintext.subarray(0, actualDigest.length))) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.PASSWORD_INVALID,
+		message: "The password is incorrect"
+	});
+	return decryptAesCbc(intermediateKey, verifierIv, material.encryptedIntermediateKey);
+};
+const assertPackageIntegrity = async (intermediateKey, material, encryptedPackage) => {
+	const ivForKey = await integrityIv(material.packageSalt, INTEGRITY_KEY_BLOCK_KEY, material.packageHash, material.cipherBlockBytes);
+	const ivForDigest = await integrityIv(material.packageSalt, INTEGRITY_DIGEST_BLOCK_KEY, material.packageHash, material.cipherBlockBytes);
+	const integrityKey = await decryptAesCbc(intermediateKey, ivForKey, material.encryptedIntegrityKey);
+	const expectedDigest = await decryptAesCbc(intermediateKey, ivForDigest, material.encryptedIntegrityDigest);
+	const hmacKey = await subtleCrypto().importKey("raw", toArrayBuffer(integrityKey), {
+		name: "HMAC",
+		hash: webHashName(material.packageHash)
+	}, false, ["sign"]);
+	const actualDigest = new Uint8Array(await subtleCrypto().sign("HMAC", hmacKey, toArrayBuffer(encryptedPackage)));
+	if (!bytesEqual(actualDigest, expectedDigest.subarray(0, actualDigest.length))) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "Data integrity check failed — the encrypted package may be corrupt or tampered with"
+	});
+};
+const decryptEncryptedPackage = async (intermediateKey, material, encryptedPackage) => {
+	if (encryptedPackage.length < PACKAGE_PLAINTEXT_SIZE_BYTES) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "EncryptedPackage stream is too short to contain a size prefix"
+	});
+	const plaintextSizeBig = new DataView(encryptedPackage.buffer, encryptedPackage.byteOffset, PACKAGE_PLAINTEXT_SIZE_BYTES).getBigUint64(0, true);
+	if (plaintextSizeBig > BigInt(Number.MAX_SAFE_INTEGER)) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "EncryptedPackage plaintext size exceeds JavaScript's safe integer range"
+	});
+	const plaintextSize = Number(plaintextSizeBig);
+	const ciphertext = encryptedPackage.subarray(PACKAGE_PLAINTEXT_SIZE_BYTES);
+	const segmentCount = Math.ceil(ciphertext.length / PACKAGE_SEGMENT_BYTES);
+	const segments = [];
+	for (let index = 0; index < segmentCount; index++) {
+		const start = index * PACKAGE_SEGMENT_BYTES;
+		const end = Math.min(start + PACKAGE_SEGMENT_BYTES, ciphertext.length);
+		const chunk = ciphertext.subarray(start, end);
+		const iv = await segmentIv(material.packageSalt, index, material.packageHash, material.cipherBlockBytes);
+		segments.push(await decryptAesCbc(intermediateKey, iv, chunk));
+	}
+	const plaintext = joinBytes(segments);
+	if (plaintextSize > plaintext.length) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "EncryptedPackage plaintext size exceeds decrypted payload length"
+	});
+	return plaintext.subarray(0, plaintextSize);
+};
+const decryptAgileEncryptedPackage = async (password, material, encryptedPackage) => {
+	try {
+		const intermediateKey = await unlockIntermediateKey(password, material);
+		await assertPackageIntegrity(intermediateKey, material, encryptedPackage);
+		return await decryptEncryptedPackage(intermediateKey, material, encryptedPackage);
+	} catch (error) {
+		if (error instanceof DocxEncryptionError) throw error;
+		throw new DocxEncryptionError({
+			code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+			message: "Decryption failed unexpectedly",
+			cause: error
+		});
+	}
+};
+//#endregion
+export { decryptAgileEncryptedPackage };

package/dist/docx/encryption/compoundFile.d.ts

@@ -0,0 +1,20 @@
+//#region src/docx/encryption/compoundFile.d.ts
+/**
+ * Read-only MS-CFB compound file access for encrypted OOXML packages.
+ *
+ * Encrypted `.docx` files store `EncryptionInfo` and `EncryptedPackage` streams
+ * at the compound-file root. This reader implements only what MS-OFFCRYPTO needs.
+ *
+ * @see https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-cfb/
+ */
+type CompoundFileReader = {
+  readStream: (absolutePath: string) => Uint8Array | null;
+};
+declare const openCompoundFile: (data: ArrayBuffer | Uint8Array) => CompoundFileReader;
+type EncryptedPackageStreams = {
+  encryptionInfo: Uint8Array;
+  encryptedPackage: Uint8Array;
+};
+declare const readEncryptedPackageStreams: (data: ArrayBuffer | Uint8Array) => EncryptedPackageStreams;
+//#endregion
+export { CompoundFileReader, EncryptedPackageStreams, openCompoundFile, readEncryptedPackageStreams };

package/dist/docx/encryption/compoundFile.js

@@ -0,0 +1,249 @@
+import { joinBytes } from "./cryptoBytes.js";
+//#region src/docx/encryption/compoundFile.ts
+/**
+* Read-only MS-CFB compound file access for encrypted OOXML packages.
+*
+* Encrypted `.docx` files store `EncryptionInfo` and `EncryptedPackage` streams
+* at the compound-file root. This reader implements only what MS-OFFCRYPTO needs.
+*
+* @see https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-cfb/
+*/
+const HEADER_BYTES = 512;
+const DIRECTORY_RECORD_BYTES = 128;
+const HEADER_DIFAT_SLOTS = 109;
+const SIGNATURE = [
+	208,
+	207,
+	17,
+	224,
+	161,
+	177,
+	26,
+	225
+];
+const LITTLE_ENDIAN_MARK = 65534;
+const SECTOR_FREE = 4294967295;
+const SECTOR_END = 4294967294;
+const SECTOR_DIFAT = 4294967292;
+const DIR_NONE = 4294967295;
+const ENTRY_KIND = {
+	STORAGE: 1,
+	STREAM: 2,
+	ROOT: 5
+};
+const viewOf = (bytes) => new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+const u16 = (view, offset) => view.getUint16(offset, true);
+const u32 = (view, offset) => view.getUint32(offset, true);
+const u64 = (view, offset) => {
+	const low = BigInt(view.getUint32(offset, true));
+	return BigInt(view.getUint32(offset + 4, true)) << 32n | low;
+};
+const decodeName = (nameBytes) => {
+	const decoded = new TextDecoder("utf-16le").decode(nameBytes);
+	let end = decoded.length;
+	while (end > 0 && decoded.charCodeAt(end - 1) === 0) end--;
+	return decoded.slice(0, end);
+};
+const sectorOffset = (sectorId, sectorBytes) => (sectorId + 1) * sectorBytes;
+const readHeader = (file) => {
+	if (file.length < HEADER_BYTES) throw new Error(`Compound file header truncated (${file.length} bytes)`);
+	for (let i = 0; i < SIGNATURE.length; i++) if (file[i] !== SIGNATURE[i]) throw new Error("Invalid compound file signature");
+	const view = viewOf(file);
+	const major = u16(view, 26);
+	const endian = u16(view, 28);
+	const sectorShift = u16(view, 30);
+	const miniShift = u16(view, 32);
+	const sectorBytes = 1 << sectorShift;
+	const miniSectorBytes = 1 << miniShift;
+	if (endian !== LITTLE_ENDIAN_MARK) throw new Error(`Unsupported compound file endianness: 0x${endian.toString(16)}`);
+	if (!(major === 3 && sectorBytes === 512 || major === 4 && sectorBytes === 4096)) throw new Error(`Unsupported compound file version ${major} (sector size ${sectorBytes})`);
+	const headerDifat = [];
+	for (let slot = 0; slot < HEADER_DIFAT_SLOTS; slot++) {
+		const id = u32(view, 76 + slot * 4);
+		if (id !== SECTOR_FREE) headerDifat.push(id);
+	}
+	return {
+		sectorBytes,
+		miniSectorBytes,
+		fatSectorCount: u32(view, 44),
+		directoryStartSector: u32(view, 48),
+		miniCutoff: u32(view, 56),
+		miniFatStart: u32(view, 60),
+		miniFatSectorCount: u32(view, 64),
+		difatStart: u32(view, 68),
+		difatSectorCount: u32(view, 72),
+		headerDifat
+	};
+};
+const loadSector = (file, header, sectorId) => {
+	if (sectorId >= SECTOR_DIFAT) throw new Error(`Invalid sector id 0x${sectorId.toString(16)}`);
+	const offset = sectorOffset(sectorId, header.sectorBytes);
+	if (offset + header.sectorBytes > file.length) throw new Error(`Sector ${sectorId} extends past end of file`);
+	return file.subarray(offset, offset + header.sectorBytes);
+};
+const loadFatSectorIds = (file, header) => {
+	const ids = [...header.headerDifat];
+	let chain = header.difatStart;
+	for (let step = 0; step < header.difatSectorCount; step++) {
+		if (chain === SECTOR_END || chain === SECTOR_FREE) break;
+		const view = viewOf(loadSector(file, header, chain));
+		const slotsPerSector = header.sectorBytes / 4 - 1;
+		for (let slot = 0; slot < slotsPerSector; slot++) {
+			const id = u32(view, slot * 4);
+			if (id !== SECTOR_FREE) ids.push(id);
+		}
+		chain = u32(view, header.sectorBytes - 4);
+	}
+	if (ids.length < header.fatSectorCount) throw new Error("DIFAT chain shorter than declared FAT sector count");
+	return ids.slice(0, header.fatSectorCount);
+};
+const loadFat = (file, header) => {
+	const table = [];
+	for (const fatSectorId of loadFatSectorIds(file, header)) {
+		const view = viewOf(loadSector(file, header, fatSectorId));
+		const entries = header.sectorBytes / 4;
+		for (let i = 0; i < entries; i++) table.push(u32(view, i * 4));
+	}
+	return table;
+};
+const followSectorChain = (file, header, fat, start) => {
+	if (start === SECTOR_END || start === SECTOR_FREE) return /* @__PURE__ */ new Uint8Array(0);
+	const parts = [];
+	const seen = /* @__PURE__ */ new Set();
+	let sectorId = start;
+	while (sectorId !== SECTOR_END) {
+		if (seen.has(sectorId)) throw new Error(`Sector chain loop at sector ${sectorId}`);
+		if (sectorId >= fat.length) throw new Error(`Sector ${sectorId} outside FAT`);
+		seen.add(sectorId);
+		parts.push(loadSector(file, header, sectorId));
+		const next = fat[sectorId];
+		if (next === void 0) throw new Error(`FAT missing link after sector ${sectorId}`);
+		sectorId = next;
+	}
+	return joinBytes(parts);
+};
+const loadDirectory = (file, header, fat) => {
+	const raw = followSectorChain(file, header, fat, header.directoryStartSector);
+	const records = [];
+	for (let pos = 0; pos + DIRECTORY_RECORD_BYTES <= raw.length; pos += DIRECTORY_RECORD_BYTES) {
+		const slice = raw.subarray(pos, pos + DIRECTORY_RECORD_BYTES);
+		const view = viewOf(slice);
+		const nameChars = Math.max(0, Math.min(u16(view, 64), 64) - 2);
+		records.push({
+			name: decodeName(slice.subarray(0, nameChars)),
+			kind: slice[66] ?? 0,
+			leftId: u32(view, 68),
+			rightId: u32(view, 72),
+			childId: u32(view, 76),
+			firstSector: u32(view, 116),
+			byteLength: (() => {
+				const size = u64(view, 120);
+				if (size > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error(`Stream too large: ${size.toString()}`);
+				return Number(size);
+			})()
+		});
+	}
+	return records;
+};
+/** Breadth-first sibling-tree walk (MS-CFB red-black sibling links). */
+const walkSiblingTree = (records, rootId, visit) => {
+	const queue = [];
+	const enqueueSubtree = (id) => {
+		if (id === DIR_NONE || id >= records.length) return;
+		const stack = [id];
+		const queued = /* @__PURE__ */ new Set();
+		while (stack.length > 0) {
+			const current = stack.pop();
+			if (queued.has(current)) throw new Error(`Directory sibling loop at entry ${current}`);
+			queued.add(current);
+			queue.push(current);
+			const node = records[current];
+			if (!node) continue;
+			if (node.leftId !== DIR_NONE) stack.push(node.leftId);
+			if (node.rightId !== DIR_NONE) stack.push(node.rightId);
+		}
+	};
+	enqueueSubtree(rootId);
+	for (const id of queue) {
+		const record = records[id];
+		if (record) visit(record);
+	}
+};
+const resolvePath = (records, path) => {
+	const parts = path.split("/").filter(Boolean);
+	const root = records[0];
+	if (!root) return null;
+	let current = root;
+	for (const part of parts) {
+		if (current.kind !== ENTRY_KIND.ROOT && current.kind !== ENTRY_KIND.STORAGE) return null;
+		let match = null;
+		walkSiblingTree(records, current.childId, (candidate) => {
+			if (candidate.name.toLowerCase() === part.toLowerCase()) match = candidate;
+		});
+		if (!match) return null;
+		current = match;
+	}
+	return current;
+};
+const loadMiniFat = (file, header, fat) => {
+	if (header.miniFatSectorCount === 0 || header.miniFatStart === SECTOR_END) return [];
+	const bytes = followSectorChain(file, header, fat, header.miniFatStart);
+	const view = viewOf(bytes);
+	const count = Math.floor(bytes.length / 4);
+	const entries = [];
+	for (let i = 0; i < count; i++) entries.push(u32(view, i * 4));
+	return entries;
+};
+const followMiniChain = (container, miniFat, miniSectorBytes, start) => {
+	if (start === SECTOR_END || start === SECTOR_FREE) return /* @__PURE__ */ new Uint8Array(0);
+	const parts = [];
+	const seen = /* @__PURE__ */ new Set();
+	let sectorId = start;
+	while (sectorId !== SECTOR_END) {
+		if (seen.has(sectorId)) throw new Error(`Mini sector chain loop at ${sectorId}`);
+		if (sectorId >= miniFat.length) throw new Error(`Mini sector ${sectorId} outside MiniFAT`);
+		seen.add(sectorId);
+		const offset = sectorId * miniSectorBytes;
+		if (offset + miniSectorBytes > container.length) throw new Error(`Mini sector ${sectorId} extends past mini stream`);
+		parts.push(container.subarray(offset, offset + miniSectorBytes));
+		const next = miniFat[sectorId];
+		if (next === void 0) throw new Error(`MiniFAT missing link after mini sector ${sectorId}`);
+		sectorId = next;
+	}
+	return joinBytes(parts);
+};
+const openCompoundFile = (data) => {
+	const file = data instanceof Uint8Array ? data : new Uint8Array(data);
+	const header = readHeader(file);
+	const fat = loadFat(file, header);
+	const directory = loadDirectory(file, header, fat);
+	const root = directory[0];
+	if (!root || root.kind !== ENTRY_KIND.ROOT) throw new Error("Compound file root entry missing");
+	const miniFat = loadMiniFat(file, header, fat);
+	const miniContainer = root.byteLength > 0 && root.firstSector !== SECTOR_END ? followSectorChain(file, header, fat, root.firstSector).subarray(0, root.byteLength) : /* @__PURE__ */ new Uint8Array(0);
+	return { readStream(absolutePath) {
+		const entry = resolvePath(directory, absolutePath);
+		if (!entry || entry.kind !== ENTRY_KIND.STREAM) return null;
+		if (entry.byteLength < header.miniCutoff) return followMiniChain(miniContainer, miniFat, header.miniSectorBytes, entry.firstSector).subarray(0, entry.byteLength);
+		return followSectorChain(file, header, fat, entry.firstSector).subarray(0, entry.byteLength);
+	} };
+};
+const readEncryptedPackageStreams = (data) => {
+	const file = data instanceof Uint8Array ? data : new Uint8Array(data);
+	let reader;
+	try {
+		reader = openCompoundFile(file);
+	} catch (cause) {
+		throw new Error("Failed to parse encrypted OOXML compound file", { cause });
+	}
+	const encryptionInfo = reader.readStream("/EncryptionInfo");
+	const encryptedPackage = reader.readStream("/EncryptedPackage");
+	if (!encryptionInfo) throw new Error("Compound file missing EncryptionInfo stream");
+	if (!encryptedPackage) throw new Error("Compound file missing EncryptedPackage stream");
+	return {
+		encryptionInfo,
+		encryptedPackage
+	};
+};
+//#endregion
+export { openCompoundFile, readEncryptedPackageStreams };

package/dist/docx/encryption/containerFormat.d.ts

@@ -0,0 +1,15 @@
+//#region src/docx/encryption/containerFormat.d.ts
+/**
+ * OOXML container format detection (ZIP vs encrypted OLE compound file).
+ *
+ * @see https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offcrypto/
+ */
+declare const DOCX_CONTAINER_TYPES: {
+  readonly ZIP: "zip";
+  readonly CFB: "cfb";
+  readonly UNKNOWN: "unknown";
+};
+type DocxContainerType = (typeof DOCX_CONTAINER_TYPES)[keyof typeof DOCX_CONTAINER_TYPES];
+declare const detectDocxContainerType: (data: ArrayBuffer | Uint8Array) => DocxContainerType;
+//#endregion
+export { DOCX_CONTAINER_TYPES, DocxContainerType, detectDocxContainerType };

package/dist/docx/encryption/containerFormat.js

@@ -0,0 +1,40 @@
+//#region src/docx/encryption/containerFormat.ts
+/**
+* OOXML container format detection (ZIP vs encrypted OLE compound file).
+*
+* @see https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offcrypto/
+*/
+const DOCX_CONTAINER_TYPES = {
+	ZIP: "zip",
+	CFB: "cfb",
+	UNKNOWN: "unknown"
+};
+const ZIP_SIGNATURE = [
+	80,
+	75,
+	3,
+	4
+];
+const OLE_SIGNATURE = [
+	208,
+	207,
+	17,
+	224,
+	161,
+	177,
+	26,
+	225
+];
+const startsWith = (bytes, signature) => {
+	if (bytes.length < signature.length) return false;
+	for (let i = 0; i < signature.length; i++) if (bytes[i] !== signature[i]) return false;
+	return true;
+};
+const detectDocxContainerType = (data) => {
+	const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+	if (startsWith(bytes, ZIP_SIGNATURE)) return DOCX_CONTAINER_TYPES.ZIP;
+	if (startsWith(bytes, OLE_SIGNATURE)) return DOCX_CONTAINER_TYPES.CFB;
+	return DOCX_CONTAINER_TYPES.UNKNOWN;
+};
+//#endregion
+export { DOCX_CONTAINER_TYPES, detectDocxContainerType };

package/dist/docx/encryption/cryptoBytes.d.ts

@@ -0,0 +1,11 @@
+//#region src/docx/encryption/cryptoBytes.d.ts
+/** Byte helpers shared by MS-CFB and MS-OFFCRYPTO agile decryption. */
+declare const joinBytes: (parts: readonly Uint8Array[]) => Uint8Array;
+declare const writeUint32Le: (value: number) => Uint8Array;
+declare const passwordToUtf16Le: (password: string) => Uint8Array;
+declare const bytesEqual: (left: Uint8Array, right: Uint8Array) => boolean;
+declare const toArrayBuffer: (bytes: Uint8Array) => ArrayBuffer;
+declare const decodeBase64: (encoded: string) => Uint8Array;
+declare const padToBlock: (bytes: Uint8Array, blockSize: number, padByte?: number) => Uint8Array;
+//#endregion
+export { bytesEqual, decodeBase64, joinBytes, padToBlock, passwordToUtf16Le, toArrayBuffer, writeUint32Le };