@stll/folio-core 0.3.1 → 0.5.0

package/dist/docx/encryption/agileDecryption.js

@@ -0,0 +1,209 @@
+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) => {
+	const algorithm = webHashName(hashName);
+	return (await digest(algorithm, 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,251 @@
+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 sector = loadSector(file, header, chain);
+		const view = viewOf(sector);
+		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 sector = loadSector(file, header, fatSectorId);
+		const view = viewOf(sector);
+		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 };

package/dist/docx/encryption/cryptoBytes.js

@@ -0,0 +1,55 @@
+//#region src/docx/encryption/cryptoBytes.ts
+/** Byte helpers shared by MS-CFB and MS-OFFCRYPTO agile decryption. */
+const joinBytes = (parts) => {
+	let total = 0;
+	for (const part of parts) total += part.length;
+	const out = new Uint8Array(total);
+	let offset = 0;
+	for (const part of parts) {
+		out.set(part, offset);
+		offset += part.length;
+	}
+	return out;
+};
+const writeUint32Le = (value) => {
+	const out = /* @__PURE__ */ new Uint8Array(4);
+	out[0] = value & 255;
+	out[1] = value >>> 8 & 255;
+	out[2] = value >>> 16 & 255;
+	out[3] = value >>> 24 & 255;
+	return out;
+};
+const passwordToUtf16Le = (password) => {
+	const out = new Uint8Array(password.length * 2);
+	for (let i = 0; i < password.length; i++) {
+		const code = password.charCodeAt(i);
+		out[i * 2] = code & 255;
+		out[i * 2 + 1] = code >> 8;
+	}
+	return out;
+};
+const bytesEqual = (left, right) => {
+	if (left.length !== right.length) return false;
+	let mismatch = 0;
+	for (let i = 0; i < left.length; i++) mismatch |= left[i] ^ right[i];
+	return mismatch === 0;
+};
+const toArrayBuffer = (bytes) => bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+const decodeBase64 = (encoded) => {
+	if (typeof atob === "function") {
+		const binary = atob(encoded);
+		const out = new Uint8Array(binary.length);
+		for (let i = 0; i < binary.length; i++) out[i] = binary.charCodeAt(i);
+		return out;
+	}
+	return new Uint8Array(Buffer.from(encoded, "base64"));
+};
+const padToBlock = (bytes, blockSize, padByte = 54) => {
+	if (bytes.length >= blockSize) return bytes.subarray(0, blockSize);
+	const out = new Uint8Array(blockSize);
+	out.set(bytes);
+	out.fill(padByte, bytes.length);
+	return out;
+};
+//#endregion
+export { bytesEqual, decodeBase64, joinBytes, padToBlock, passwordToUtf16Le, toArrayBuffer, writeUint32Le };

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

@@ -0,0 +1,32 @@
+//#region src/docx/encryption/encryptionInfo.d.ts
+/**
+ * Parse the EncryptionInfo stream for Agile Encryption (Office 2010+).
+ *
+ * @see https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offcrypto/87020a34-e73f-4139-99bc-bbdf6cf6fa55
+ */
+type AgileKeyMaterial = {
+  packageSalt: Uint8Array;
+  packageKeyBits: number;
+  packageHash: string;
+  packageHashBytes: number;
+  cipherBlockBytes: number;
+  cipherName: string;
+  cipherMode: string;
+  passwordIterations: number;
+  passwordSalt: Uint8Array;
+  passwordHash: string;
+  passwordKeyBits: number;
+  passwordBlockBytes: number;
+  encryptedVerifierInput: Uint8Array;
+  encryptedVerifierDigest: Uint8Array;
+  encryptedIntermediateKey: Uint8Array;
+  encryptedIntegrityKey: Uint8Array;
+  encryptedIntegrityDigest: Uint8Array;
+};
+type AgileEncryptionDescriptor = {
+  scheme: "agile";
+  material: AgileKeyMaterial;
+};
+declare const parseAgileEncryptionInfo: (stream: Uint8Array) => AgileEncryptionDescriptor;
+//#endregion
+export { AgileEncryptionDescriptor, AgileKeyMaterial, parseAgileEncryptionInfo };