@stll/folio-core 0.3.1 → 0.4.0

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 };

package/dist/docx/encryption/encryptionInfo.js

@@ -0,0 +1,128 @@
+import { decodeBase64 } from "./cryptoBytes.js";
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError } from "./errors.js";
+//#region src/docx/encryption/encryptionInfo.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
+*/
+const AGILE_STREAM_VERSION = 4;
+const AGILE_STREAM_KIND = 4;
+const STANDARD_STREAM_KIND = 3;
+const STREAM_PREFIX_BYTES = 8;
+const readUint16Le = (bytes, offset) => bytes[offset] | bytes[offset + 1] << 8;
+const findElement = (xml, localName) => {
+	let index = 0;
+	while (index < xml.length) {
+		const hit = xml.indexOf(localName, index);
+		if (hit === -1) return null;
+		const tagStart = xml.lastIndexOf("<", hit);
+		if (tagStart === -1 || hit - tagStart > 24) {
+			index = hit + localName.length;
+			continue;
+		}
+		const tagEnd = xml.indexOf(">", hit);
+		if (tagEnd === -1) return null;
+		const tag = xml.slice(tagStart, tagEnd + 1);
+		if (tag.includes(localName)) return tag;
+		index = hit + localName.length;
+	}
+	return null;
+};
+const parseAttributes = (tag) => {
+	const attrs = {};
+	let i = tag.indexOf(" ");
+	if (i === -1) return attrs;
+	while (i < tag.length) {
+		while (i < tag.length && (tag[i] === " " || tag[i] === "\n" || tag[i] === "\r" || tag[i] === "	")) i++;
+		const nameStart = i;
+		while (i < tag.length && tag[i] !== "=" && tag[i] !== ">" && tag[i] !== "/") i++;
+		if (i >= tag.length || tag[i] !== "=") break;
+		const name = tag.slice(nameStart, i).trim();
+		i++;
+		const quote = tag[i];
+		if (quote !== "\"" && quote !== "'") break;
+		i++;
+		const valueStart = i;
+		while (i < tag.length && tag[i] !== quote) i++;
+		if (i >= tag.length) break;
+		attrs[name] = tag.slice(valueStart, i);
+		i++;
+	}
+	return attrs;
+};
+const requireAttr = (attrs, name, element) => {
+	const value = attrs[name];
+	if (value === void 0) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: `EncryptionInfo <${element}> missing attribute "${name}"`
+	});
+	return value;
+};
+const requireInt = (attrs, name, element) => {
+	const parsed = Number.parseInt(requireAttr(attrs, name, element), 10);
+	if (Number.isNaN(parsed)) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: `EncryptionInfo <${element}> attribute "${name}" is not an integer`
+	});
+	return parsed;
+};
+const requireBase64 = (attrs, name, element) => decodeBase64(requireAttr(attrs, name, element));
+const parseAgileXml = (xmlBytes) => {
+	const xml = new TextDecoder("utf-8").decode(xmlBytes);
+	const keyDataTag = findElement(xml, "keyData");
+	const integrityTag = findElement(xml, "dataIntegrity");
+	const encryptedKeyTag = findElement(xml, "encryptedKey");
+	if (!keyDataTag || !integrityTag || !encryptedKeyTag) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "EncryptionInfo XML is missing required agile encryption elements"
+	});
+	const keyData = parseAttributes(keyDataTag);
+	const integrity = parseAttributes(integrityTag);
+	const encryptedKey = parseAttributes(encryptedKeyTag);
+	return {
+		packageSalt: requireBase64(keyData, "saltValue", "keyData"),
+		packageKeyBits: requireInt(keyData, "keyBits", "keyData"),
+		packageHash: requireAttr(keyData, "hashAlgorithm", "keyData"),
+		packageHashBytes: requireInt(keyData, "hashSize", "keyData"),
+		cipherBlockBytes: requireInt(keyData, "blockSize", "keyData"),
+		cipherName: requireAttr(keyData, "cipherAlgorithm", "keyData"),
+		cipherMode: requireAttr(keyData, "cipherChaining", "keyData"),
+		passwordIterations: requireInt(encryptedKey, "spinCount", "encryptedKey"),
+		passwordSalt: requireBase64(encryptedKey, "saltValue", "encryptedKey"),
+		passwordHash: requireAttr(encryptedKey, "hashAlgorithm", "encryptedKey"),
+		passwordKeyBits: requireInt(encryptedKey, "keyBits", "encryptedKey"),
+		passwordBlockBytes: requireInt(encryptedKey, "blockSize", "encryptedKey"),
+		encryptedVerifierInput: requireBase64(encryptedKey, "encryptedVerifierHashInput", "encryptedKey"),
+		encryptedVerifierDigest: requireBase64(encryptedKey, "encryptedVerifierHashValue", "encryptedKey"),
+		encryptedIntermediateKey: requireBase64(encryptedKey, "encryptedKeyValue", "encryptedKey"),
+		encryptedIntegrityKey: requireBase64(integrity, "encryptedHmacKey", "dataIntegrity"),
+		encryptedIntegrityDigest: requireBase64(integrity, "encryptedHmacValue", "dataIntegrity")
+	};
+};
+const parseAgileEncryptionInfo = (stream) => {
+	if (stream.length < STREAM_PREFIX_BYTES) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: `EncryptionInfo stream too short (${stream.length} bytes)`
+	});
+	const version = readUint16Le(stream, 0);
+	const kind = readUint16Le(stream, 2);
+	if (version === AGILE_STREAM_VERSION && kind === AGILE_STREAM_KIND) return {
+		scheme: "agile",
+		material: parseAgileXml(stream.subarray(STREAM_PREFIX_BYTES))
+	};
+	if ((version === 3 || version === AGILE_STREAM_VERSION) && kind === STANDARD_STREAM_KIND) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.ENCRYPTION_UNSUPPORTED,
+		message: "Standard Encryption (Office 2007) is not supported. Only Agile Encryption (Office 2010+) is supported."
+	});
+	if (version <= 2) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.ENCRYPTION_UNSUPPORTED,
+		message: "Legacy RC4 encryption is not supported. Only Agile Encryption (Office 2010+) is supported."
+	});
+	throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.ENCRYPTION_UNSUPPORTED,
+		message: `Unrecognized EncryptionInfo header version=${version} kind=${kind}`
+	});
+};
+//#endregion
+export { parseAgileEncryptionInfo };

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

@@ -0,0 +1,18 @@
+//#region src/docx/encryption/errors.d.ts
+/** Machine-readable codes for password-protected OOXML failures. */
+declare const DOCX_ENCRYPTION_ERROR_CODES: {
+  readonly PASSWORD_REQUIRED: "DOCX_PASSWORD_REQUIRED";
+  readonly PASSWORD_INVALID: "DOCX_PASSWORD_INVALID";
+  readonly ENCRYPTION_UNSUPPORTED: "DOCX_ENCRYPTION_UNSUPPORTED";
+  readonly DECRYPTION_FAILED: "DOCX_DECRYPTION_FAILED";
+};
+type DocxEncryptionErrorCode = (typeof DOCX_ENCRYPTION_ERROR_CODES)[keyof typeof DOCX_ENCRYPTION_ERROR_CODES];
+declare const DocxEncryptionError_base: import("better-result").TaggedErrorClass<"DocxEncryptionError", {
+  message: string;
+  code: DocxEncryptionErrorCode;
+  cause?: unknown;
+}>;
+declare class DocxEncryptionError extends DocxEncryptionError_base {}
+declare const isDocxEncryptionError: (error: unknown) => error is DocxEncryptionError;
+//#endregion
+export { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, DocxEncryptionErrorCode, isDocxEncryptionError };

package/dist/docx/encryption/errors.js

@@ -0,0 +1,13 @@
+import { TaggedError } from "better-result";
+//#region src/docx/encryption/errors.ts
+/** Machine-readable codes for password-protected OOXML failures. */
+const DOCX_ENCRYPTION_ERROR_CODES = {
+	PASSWORD_REQUIRED: "DOCX_PASSWORD_REQUIRED",
+	PASSWORD_INVALID: "DOCX_PASSWORD_INVALID",
+	ENCRYPTION_UNSUPPORTED: "DOCX_ENCRYPTION_UNSUPPORTED",
+	DECRYPTION_FAILED: "DOCX_DECRYPTION_FAILED"
+};
+var DocxEncryptionError = class extends TaggedError("DocxEncryptionError")() {};
+const isDocxEncryptionError = (error) => error instanceof DocxEncryptionError;
+//#endregion
+export { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, isDocxEncryptionError };

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

@@ -0,0 +1,4 @@
+import { DOCX_CONTAINER_TYPES, DocxContainerType, detectDocxContainerType } from "./containerFormat.js";
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, DocxEncryptionErrorCode, isDocxEncryptionError } from "./errors.js";
+import { DecryptDocxOptions, DecryptDocxResult, decryptDocxIfNeeded, openDocxBuffer } from "./openEncryptedDocx.js";
+export { DOCX_CONTAINER_TYPES, DOCX_ENCRYPTION_ERROR_CODES, type DecryptDocxOptions, type DecryptDocxResult, type DocxContainerType, DocxEncryptionError, type DocxEncryptionErrorCode, decryptDocxIfNeeded, detectDocxContainerType, isDocxEncryptionError, openDocxBuffer };

package/dist/docx/encryption/index.js

@@ -0,0 +1,4 @@
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, isDocxEncryptionError } from "./errors.js";
+import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "./containerFormat.js";
+import { decryptDocxIfNeeded, openDocxBuffer } from "./openEncryptedDocx.js";
+export { DOCX_CONTAINER_TYPES, DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, decryptDocxIfNeeded, detectDocxContainerType, isDocxEncryptionError, openDocxBuffer };

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

@@ -0,0 +1,28 @@
+//#region src/docx/encryption/openEncryptedDocx.d.ts
+/**
+ * Decrypt password-protected OOXML before ZIP extraction.
+ *
+ * Implementation is derived from [MS-OFFCRYPTO] and [MS-CFB] only.
+ *
+ * @see https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offcrypto/
+ */
+type DecryptDocxOptions = {
+  /** Password for Agile-encrypted .docx files (Office 2010+). */password?: string | undefined;
+};
+type DecryptDocxResult = {
+  /** Plaintext OOXML ZIP bytes, or the original buffer when unencrypted. */data: ArrayBuffer; /** True when the input was an encrypted CFB container and decryption ran. */
+  wasEncrypted: boolean;
+};
+/**
+ * Decrypt a password-protected `.docx` when needed, or return the input unchanged.
+ *
+ * Supports Agile Encryption (Office 2010+). Standard Encryption and legacy RC4
+ * are rejected with `DOCX_ENCRYPTION_UNSUPPORTED`.
+ *
+ * Save produces a standard unencrypted OOXML ZIP; folio does not re-encrypt on export.
+ */
+declare const decryptDocxIfNeeded: (data: ArrayBuffer | Uint8Array, options?: DecryptDocxOptions) => Promise<DecryptDocxResult>;
+/** Open a `.docx` buffer for parsing: decrypt when encrypted, then return the ZIP bytes. */
+declare const openDocxBuffer: (data: ArrayBuffer | Uint8Array, options?: DecryptDocxOptions) => Promise<ArrayBuffer>;
+//#endregion
+export { DecryptDocxOptions, DecryptDocxResult, decryptDocxIfNeeded, openDocxBuffer };

package/dist/docx/encryption/openEncryptedDocx.js

@@ -0,0 +1,65 @@
+import { toArrayBuffer } from "./cryptoBytes.js";
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError } from "./errors.js";
+import { decryptAgileEncryptedPackage } from "./agileDecryption.js";
+import { readEncryptedPackageStreams } from "./compoundFile.js";
+import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "./containerFormat.js";
+import { parseAgileEncryptionInfo } from "./encryptionInfo.js";
+//#region src/docx/encryption/openEncryptedDocx.ts
+/**
+* Decrypt password-protected OOXML before ZIP extraction.
+*
+* Implementation is derived from [MS-OFFCRYPTO] and [MS-CFB] only.
+*
+* @see https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offcrypto/
+*/
+const assertZipPayload = (bytes) => {
+	if (detectDocxContainerType(bytes) !== DOCX_CONTAINER_TYPES.ZIP) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "Decrypted output is not a valid ZIP archive — the file may be corrupt"
+	});
+};
+/**
+* Decrypt a password-protected `.docx` when needed, or return the input unchanged.
+*
+* Supports Agile Encryption (Office 2010+). Standard Encryption and legacy RC4
+* are rejected with `DOCX_ENCRYPTION_UNSUPPORTED`.
+*
+* Save produces a standard unencrypted OOXML ZIP; folio does not re-encrypt on export.
+*/
+const decryptDocxIfNeeded = async (data, options = {}) => {
+	const bytes = data instanceof Uint8Array ? data : new Uint8Array(data);
+	const container = detectDocxContainerType(bytes);
+	if (container === DOCX_CONTAINER_TYPES.ZIP) return {
+		data: toArrayBuffer(bytes),
+		wasEncrypted: false
+	};
+	if (container !== DOCX_CONTAINER_TYPES.CFB) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+		message: "Unrecognized file format — expected a .docx (ZIP) or encrypted .docx (OLE/CFB)"
+	});
+	if (options.password == null) throw new DocxEncryptionError({
+		code: DOCX_ENCRYPTION_ERROR_CODES.PASSWORD_REQUIRED,
+		message: "This document is password-protected. A password is required to open it."
+	});
+	let streams;
+	try {
+		streams = readEncryptedPackageStreams(bytes);
+	} catch (cause) {
+		throw new DocxEncryptionError({
+			code: DOCX_ENCRYPTION_ERROR_CODES.DECRYPTION_FAILED,
+			message: "Failed to read encrypted OOXML streams",
+			cause
+		});
+	}
+	const descriptor = parseAgileEncryptionInfo(streams.encryptionInfo);
+	const decryptedZip = await decryptAgileEncryptedPackage(options.password, descriptor.material, streams.encryptedPackage);
+	assertZipPayload(decryptedZip);
+	return {
+		data: toArrayBuffer(decryptedZip),
+		wasEncrypted: true
+	};
+};
+/** Open a `.docx` buffer for parsing: decrypt when encrypted, then return the ZIP bytes. */
+const openDocxBuffer = async (data, options = {}) => (await decryptDocxIfNeeded(data, options)).data;
+//#endregion
+export { decryptDocxIfNeeded, openDocxBuffer };

package/dist/docx/index.d.ts

@@ -1,2 +1,4 @@
 import { getCachedNumberingMap } from "./numberingParser.js";
-export { getCachedNumberingMap };
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, DocxEncryptionErrorCode, isDocxEncryptionError } from "./encryption/errors.js";
+import { DecryptDocxOptions, DecryptDocxResult, decryptDocxIfNeeded, openDocxBuffer } from "./encryption/openEncryptedDocx.js";
+export { DOCX_ENCRYPTION_ERROR_CODES, type DecryptDocxOptions, type DecryptDocxResult, DocxEncryptionError, type DocxEncryptionErrorCode, decryptDocxIfNeeded, getCachedNumberingMap, isDocxEncryptionError, openDocxBuffer };

package/dist/docx/index.js

@@ -1,2 +1,4 @@
 import { getCachedNumberingMap } from "./numberingParser.js";
-export { getCachedNumberingMap };
+import { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, isDocxEncryptionError } from "./encryption/errors.js";
+import { decryptDocxIfNeeded, openDocxBuffer } from "./encryption/openEncryptedDocx.js";
+export { DOCX_ENCRYPTION_ERROR_CODES, DocxEncryptionError, decryptDocxIfNeeded, getCachedNumberingMap, isDocxEncryptionError, openDocxBuffer };

package/dist/docx/parser.d.ts

@@ -1,5 +1,5 @@
 import { document_d_exports } from "../types/document.js";
-import { DocxUnzipLimits } from "./unzip.js";
+import { DocxUnzipOptions } from "./unzip.js";
 import { DocxInput } from "../utils/docxInput.js";
 
 //#region src/docx/parser.d.ts
@@ -24,10 +24,9 @@ type ParseOptions = {
   preloadFonts?: boolean; /** Whether to parse headers/footers (default: true) */
   parseHeadersFooters?: boolean; /** Whether to parse footnotes/endnotes (default: true) */
   parseNotes?: boolean; /** Whether to detect template variables (default: true) */
-  detectVariables?: boolean; /** Security limits for DOCX ZIP extraction */
-  unzipLimits?: Partial<Omit<DocxUnzipLimits, "allowedMediaMimeTypes">> & {
-    allowedMediaMimeTypes?: Iterable<string>;
-  }; /** Optional async hook to override display URLs for non-browser media. */
+  detectVariables?: boolean; /** Password for Agile-encrypted .docx files (Office 2010+). */
+  password?: string | undefined; /** Security limits for DOCX ZIP extraction */
+  unzipLimits?: DocxUnzipOptions; /** Optional async hook to override display URLs for non-browser media. */
   mediaResolver?: MediaResolver;
 };
 /**

package/dist/docx/parser.js

@@ -3,6 +3,7 @@ import { applyThemeFontLang, parseTheme } from "./themeParser.js";
 import { parseEndnotes, parseFootnotes } from "./footnoteParser.js";
 import { DocxModelValidationError, formatDocumentModelIssues, validateFolioDocumentModel } from "./modelValidation.js";
 import { parseNumbering } from "./numberingParser.js";
+import { DocxEncryptionError } from "./encryption/errors.js";
 import { getMediaMimeType, mediaToDataUrl, unzipDocx } from "./unzip.js";
 import { parseComments } from "./commentParser.js";
 import { parseFooter, parseHeader } from "./headerFooterParser.js";
@@ -48,13 +49,17 @@ import { TaggedError } from "better-result";
 */
 async function parseDocx(input, options = {}) {
 	const buffer = input instanceof ArrayBuffer ? input : await toArrayBuffer(input);
-	const { onProgress = () => {}, preloadFonts = true, parseHeadersFooters = true, parseNotes = true, detectVariables = true, unzipLimits, mediaResolver } = options;
+	const { onProgress = () => {}, preloadFonts = true, parseHeadersFooters = true, parseNotes = true, detectVariables = true, password, unzipLimits, mediaResolver } = options;
 	const warnings = [];
 	try {
 		const timeStage = (_name, fn) => fn();
 		const timeStageAsync = async (_name, fn) => await fn();
 		onProgress("Extracting DOCX...", 0);
-		const raw = await timeStageAsync("unzip", () => unzipDocx(buffer, unzipLimits));
+		const raw = await timeStageAsync("unzip", () => unzipDocx(buffer, {
+			...unzipLimits,
+			password
+		}));
+		if (raw.wasEncrypted) warnings.push("Document was opened from password-protected storage; saving writes an unencrypted .docx file.");
 		warnings.push(...raw.warnings);
 		onProgress("Extracted DOCX", 10);
 		onProgress("Parsing relationships...", 10);
@@ -186,6 +191,7 @@ async function parseDocx(input, options = {}) {
 		onProgress("Complete", 100);
 		return document;
 	} catch (error) {
+		if (error instanceof DocxEncryptionError) throw error;
 		throw new DocxParseError({
 			message: `Failed to parse DOCX: ${error instanceof Error ? error.message : String(error)}`,
 			cause: error

package/dist/docx/unzip.d.ts

@@ -13,8 +13,9 @@ type DocxUnzipLimits = {
   maxTotalUncompressedBytes: number;
   allowedMediaMimeTypes: ReadonlySet<string>;
 };
-type PartialDocxUnzipLimits = Partial<Omit<DocxUnzipLimits, "allowedMediaMimeTypes">> & {
-  allowedMediaMimeTypes?: Iterable<string>;
+type DocxUnzipOptions = Partial<Omit<DocxUnzipLimits, "allowedMediaMimeTypes">> & {
+  allowedMediaMimeTypes?: Iterable<string>; /** Password for Agile-encrypted .docx files (Office 2010+). */
+  password?: string | undefined;
 };
 /**
  * Raw extracted content from a DOCX file
@@ -45,7 +46,8 @@ type RawDocxContent = {
   allXml: Map<string, string>;
   originalZip: JSZip;
   originalBuffer: ArrayBuffer;
-  warnings: string[];
+  warnings: string[]; /** True when the input was a password-protected CFB container. */
+  wasEncrypted: boolean;
 };
 /**
  * Extract all content from a DOCX file
@@ -53,7 +55,7 @@ type RawDocxContent = {
  * @param buffer - DOCX file as ArrayBuffer
  * @returns Promise resolving to extracted content
  */
-declare function unzipDocx(buffer: ArrayBuffer, options?: PartialDocxUnzipLimits): Promise<RawDocxContent>;
+declare function unzipDocx(buffer: ArrayBuffer, options?: DocxUnzipOptions): Promise<RawDocxContent>;
 declare function isPreservableDocxEntry(path: string): boolean;
 /**
  * Get a list of all files in the DOCX
@@ -115,4 +117,4 @@ declare function getContentSummary(content: RawDocxContent): {
   totalFiles: number;
 };
 //#endregion
-export { DocxSecurityError, DocxUnzipLimits, RawDocxContent, extractFile, getContentSummary, getFileList, getMediaMimeType, hasFile, isPreservableDocxEntry, mediaToDataUrl, unzipDocx };
+export { DocxSecurityError, DocxUnzipLimits, DocxUnzipOptions, RawDocxContent, extractFile, getContentSummary, getFileList, getMediaMimeType, hasFile, isPreservableDocxEntry, mediaToDataUrl, unzipDocx };

package/dist/docx/unzip.js

@@ -1,3 +1,5 @@
+import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "./encryption/containerFormat.js";
+import { openDocxBuffer } from "./encryption/openEncryptedDocx.js";
 import JSZip from "jszip";
 //#region src/docx/unzip.ts
 /**
@@ -71,7 +73,10 @@ const ZIP_CENTRAL_DIRECTORY_FILE_HEADER_SIZE = 46;
 async function unzipDocx(buffer, options = {}) {
 	const limits = createUnzipLimits(options);
 	if (buffer.byteLength > limits.maxInputBytes) throw new DocxSecurityError("DOCX file exceeds the maximum allowed size");
-	const loaded = await loadDocxZip(buffer, limits.maxFiles);
+	const zipBuffer = await openDocxBuffer(buffer, { password: options.password });
+	if (zipBuffer.byteLength > limits.maxInputBytes) throw new DocxSecurityError("DOCX file exceeds the maximum allowed size");
+	const wasEncrypted = detectDocxContainerType(buffer) === DOCX_CONTAINER_TYPES.CFB;
+	const loaded = await loadDocxZip(zipBuffer, limits.maxFiles);
 	if (loaded.buffer.byteLength > limits.maxInputBytes) throw new DocxSecurityError("DOCX file exceeds the maximum allowed size");
 	const { zip } = loaded;
 	const entries = Object.entries(zip.files).filter(([, file]) => !file.dir);
@@ -102,7 +107,8 @@ async function unzipDocx(buffer, options = {}) {
 		allXml: /* @__PURE__ */ new Map(),
 		originalZip: zip,
 		originalBuffer: loaded.buffer,
-		warnings: []
+		warnings: [],
+		wasEncrypted
 	};
 	let totalUncompressedBytes = 0;
 	for (const [path, file] of entries) {

package/dist/layout-bridge/convert/headerFooterLayout.d.ts

@@ -12,7 +12,7 @@ type HeaderFooterMetrics = {
   };
   margins: PageMargins;
 };
-declare function normalizeHeaderFooterMeasureBlocks(blocks: FlowBlock[]): FlowBlock[];
+declare function normalizeHeaderFooterMeasureBlocks(blocks: FlowBlock[], section?: HeaderFooterMetrics["section"]): FlowBlock[];
 declare function resolveHeaderFooterPositionedVisualTop(position: ImageRunPosition | undefined, elementHeight: number, sourceY: number, flowHeight: number, metrics: HeaderFooterMetrics): number;
 declare function resolveHeaderFooterVisualTop(run: ImageRun, paragraphY: number, flowHeight: number, metrics: HeaderFooterMetrics): number;
 declare function calculateHeaderFooterVisualBounds(blocks: FlowBlock[], measures: Measure[], flowHeight: number, metrics: HeaderFooterMetrics): {

package/dist/layout-bridge/convert/headerFooterLayout.js

@@ -16,13 +16,13 @@ function hasAuthoredVisualContent(block) {
 	if (attrs.spacingExplicit?.before || attrs.spacingExplicit?.after) return true;
 	return false;
 }
-function normalizeHeaderFooterMeasureBlocks(blocks) {
-	return normalizeFlowBlockArray(blocks);
+function normalizeHeaderFooterMeasureBlocks(blocks, section = "header") {
+	return normalizeFlowBlockArray(blocks, { suppressTrailingEmptyAfterTable: section === "header" });
 }
-function normalizeFlowBlockArray(blocks) {
+function normalizeFlowBlockArray(blocks, normalization) {
 	const trailingEmptyAfterTable = /* @__PURE__ */ new Set();
 	const lastIndex = blocks.length - 1;
-	if (lastIndex > 0) {
+	if (normalization.suppressTrailingEmptyAfterTable && lastIndex > 0) {
 		const cur = blocks[lastIndex];
 		if (blocks[lastIndex - 1]?.kind === "table" && cur?.kind === "paragraph" && cur.runs.length === 0 && !hasAuthoredVisualContent(cur)) trailingEmptyAfterTable.add(lastIndex);
 	}
@@ -70,12 +70,21 @@ function normalizeFlowBlockArray(blocks) {
 		};
 	});
 }
+function isCanonicalTrailingEmptyParagraphAfterTable(blocks, index) {
+	const cur = blocks[index];
+	const prev = blocks[index - 1];
+	return index === blocks.length - 1 && prev?.kind === "table" && cur?.kind === "paragraph" && isVisuallyEmptyParagraph(cur) && !hasAuthoredVisualContent(cur);
+}
+function isVisuallyEmptyParagraph(block) {
+	if (block.kind !== "paragraph") return false;
+	return block.runs.every((run) => run.kind === "text" && run.text.trim().length === 0);
+}
 function normalizeTableBlock(block) {
 	const blockState = { changed: false };
 	const rows = block.rows.map((row) => {
 		const rowState = { changed: false };
 		const cells = row.cells.map((cell) => {
-			const normalizedBlocks = normalizeFlowBlockArray(cell.blocks);
+			const normalizedBlocks = normalizeFlowBlockArray(cell.blocks, { suppressTrailingEmptyAfterTable: true });
 			if (!normalizedBlocks.some((normalizedBlock, idx) => normalizedBlock !== cell.blocks[idx])) return cell;
 			rowState.changed = true;
 			return {
@@ -232,6 +241,7 @@ function calculateHeaderFooterMarginPushBounds(blocks, measures, flowHeight, met
 		const block = blocks[i];
 		const measure = measures[i];
 		if (!block || !measure) continue;
+		if (isCanonicalTrailingEmptyParagraphAfterTable(blocks, i)) continue;
 		if (block.kind === "paragraph" && measure.kind === "paragraph") {
 			const paragraphBottomY = cursorY + measure.totalHeight;
 			top = Math.min(top, cursorY);
@@ -312,7 +322,7 @@ function convertHeaderFooterPmDocToContent(pmDoc, contentWidth, metrics, options
 }
 function finalizeHeaderFooterContent(blocks, contentWidth, metrics, options) {
 	if (blocks.length === 0) return;
-	const blocksForMeasure = normalizeHeaderFooterMeasureBlocks(blocks);
+	const blocksForMeasure = normalizeHeaderFooterMeasureBlocks(blocks, metrics.section);
 	const measures = options.measureBlocks(blocksForMeasure, contentWidth);
 	let flowHeight = 0;
 	for (let i = 0; i < measures.length; i++) {

package/dist/layout-bridge/convert/toFlowBlocks.js

@@ -732,6 +732,7 @@ function convertParagraphAttrs(pmAttrs, theme, listCounters, listAbstractCounter
 	if (pmAttrs.pageBreakBefore) attrs.pageBreakBefore = true;
 	if (pmAttrs.keepNext) attrs.keepNext = true;
 	if (pmAttrs.keepLines) attrs.keepLines = true;
+	if (pmAttrs.widowControl === false) attrs.widowControl = false;
 	if (pmAttrs.contextualSpacing) attrs.contextualSpacing = true;
 	if (pmAttrs.runInWithNext) attrs.runInWithNext = true;
 	if (directionIsRtl(pmAttrs.direction)) attrs.bidi = true;
@@ -941,6 +942,7 @@ function convertTableRow(node, startPos, options, tableCellMargins) {
 	if (attrs.height) row.height = twipsToPixels(attrs.height);
 	if (attrs.heightRule) row.heightRule = attrs.heightRule;
 	if (attrs.isHeader) row.isHeader = attrs.isHeader;
+	if (attrs.hidden) row.hidden = attrs.hidden;
 	return row;
 }
 /**

package/dist/layout-engine/index.js

@@ -72,6 +72,9 @@ function getSpacingAfter(block) {
 	if (isEmptyParagraph(block) && !block.attrs?.spacingExplicit?.after) return 0;
 	return value;
 }
+function hasWidowControl(block) {
+	return block.attrs?.widowControl !== false;
+}
 /**
 * Apply contextual spacing suppression (OOXML §17.3.1.9).
 *
@@ -309,6 +312,28 @@ function layoutParagraph(block, measure, paginator, contentWidth, footnoteHeight
 				fittingLines++;
 			} else break;
 		}
+		let forceBreakAfterFragment = false;
+		if (hasWidowControl(block)) {
+			const remainingAfter = lines.length - (currentLineIndex + fittingLines);
+			if (fittingLines > 1 && remainingAfter === 1) {
+				if (currentLineIndex === 0 && fittingLines === 2 && state.cursorY !== state.topMargin) {
+					paginator.forceColumnBreak();
+					continue;
+				}
+				fittingLines -= 1;
+				forceBreakAfterFragment = true;
+				linesHeight = 0;
+				linesFnHeight = 0;
+				linesFnIds.length = 0;
+				for (let j = currentLineIndex; j < currentLineIndex + fittingLines; j++) {
+					const line = lines[j];
+					linesHeight += measuredLineAdvance(line);
+					const lineRefs = getLineFootnoteRefs(block, line.fromRun, line.toRun, footnoteHeightById);
+					linesFnHeight += lineRefs.height;
+					for (const id of lineRefs.ids) linesFnIds.push(id);
+				}
+			}
+		}
 		const isFirstFragment = currentLineIndex === 0;
 		const isLastFragment = currentLineIndex + fittingLines >= lines.length;
 		const effectiveSpaceBefore = isFirstFragment ? spaceBefore : 0;
@@ -336,7 +361,8 @@ function layoutParagraph(block, measure, paginator, contentWidth, footnoteHeight
 		fragment.y = paginator.addFragment(fragment, linesHeight, effectiveSpaceBefore, effectiveSpaceAfter).y;
 		if (linesFnHeight > 0) paginator.addFootnoteHeight(linesFnHeight, linesFnIds);
 		currentLineIndex += fittingLines;
-		if (currentLineIndex < lines.length) paginator.ensureFits(measuredLineAdvance(lines[currentLineIndex]));
+		if (currentLineIndex < lines.length) if (forceBreakAfterFragment) paginator.forceColumnBreak();
+		else paginator.ensureFits(measuredLineAdvance(lines[currentLineIndex]));
 	}
 }
 /**