@stll/folio-core 0.3.0 → 0.4.0

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

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,6 +1,6 @@
 import { document_d_exports } from "../types/document.js";
+import { DocxUnzipOptions } from "./unzip.js";
 import { DocxInput } from "../utils/docxInput.js";
-import { DocxUnzipLimits } from "./unzip.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/index.d.ts

@@ -8,21 +8,22 @@ import { AIBarStatus, AIChatMode, AICitation, AICitationSource, AIGenerateInput,
 import { ApplyResult, applySuggestions } from "./ai-suggestions/apply.js";
 import { ResolvedAnchor, isSuggestionStale, resolveSuggestionAnchor } from "./ai-suggestions/conflict.js";
 import { PositionalText, buildPositionalText } from "./ai-suggestions/text-positions.js";
-import { TemplatePreviewSpan, TemplatePreviewValue, TemplatePreviewValues, setTemplatePreviewValues } from "./prosemirror/plugins/templatePreviewValues.js";
-import { DocxCompatibility } from "./docx/compatibility.js";
-import { createDocx } from "./docx/rezip.js";
-import { EmbeddedFont, EmbeddedFontParts, extractEmbeddedFonts, getEmbeddedFontFaces } from "./fonts/embeddedFonts.js";
 import { CreateEmptyDocumentOptions, createEmptyDocument } from "./utils/createDocument.js";
+import { createDocx } from "./docx/rezip.js";
+import { DocxCompatibility } from "./docx/compatibility.js";
 import { setAISuggestionsMeta, setFocusedSuggestionMeta } from "./prosemirror/plugins/aiSuggestionDecorations.js";
 import { scrollFolioPositionIntoView } from "./paged-layout/scrollToPmPosition.js";
 import { getFolioCaretViewportRect, getFolioSelectionViewportRect } from "./paged-layout/selectionViewportRect.js";
 import { AICitationRange, createAICitationDecorationsPlugin, setAICitationsMeta, setActiveCitationMeta } from "./prosemirror/plugins/aiCitationDecorations.js";
 import { AnonymizationMatch, AnonymizationTerm, anonymizationDecorationsKey, getAnonymizationMatches, setAnonymizationTermsMeta } from "./prosemirror/plugins/anonymizationDecorations.js";
 import { DirectiveKind, DirectiveRange, getTemplateDirectives, scanDirectives } from "./prosemirror/plugins/templateDirectives.js";
+import { TemplatePreviewSpan, TemplatePreviewValue, TemplatePreviewValues, setTemplatePreviewValues } from "./prosemirror/plugins/templatePreviewValues.js";
 import { TemplateSlashMenuKeyAction, TemplateSlashMenuState, clearTemplateSlashMenu, consumeTemplateSlashQuery, getTemplateSlashMenu, resetTemplateSlashQuery, templateSlashMenuKey } from "./prosemirror/plugins/templateSlashMenu.js";
 import { AcceptAutocompleteResult, AutocompleteSuggestionPluginOptions, AutocompleteSuggestionState, AutocompleteSuggestionStatus, AutocompleteTriggerCheck, AutocompleteTriggerOptions, AutocompleteTriggerSkipReason, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, acceptAutocompleteSuggestion, acceptAutocompleteWord, appendAutocompleteToken, autocompleteSuggestionKey, autocompleteSuggestionPlugin, clearAutocompleteSuggestion, finishAutocompleteSuggestion, getAutocompleteSuggestion, shouldTriggerAutocomplete, startAutocompleteSuggestion } from "./prosemirror/plugins/autocompleteSuggestion.js";
 import { ImageMeta, ImageRef, MarkdownOptions, MarkdownResult } from "./markdown/types.js";
 import { fromMarkdown } from "./markdown/fromMarkdown.js";
 import { toMarkdown, toMarkdownResult } from "./markdown/index.js";
+import { EmbeddedFont, EmbeddedFontParts, extractEmbeddedFonts, getEmbeddedFontFaces } from "./fonts/embeddedFonts.js";
+import { getGoogleFontsEnabled, setGoogleFontsEnabled } from "./utils/fontResolver.js";
 type Document = document_d_exports.Document;
-export { type AIBarStatus, type AIChatMode, type AICitation, type AICitationRange, type AICitationSource, type AIGenerateInput, type AISuggestion, type AISuggestionApplyMode, type AISuggestionPreset, type AISuggestionSeverity, type AISuggestionStatus, type AcceptAutocompleteResult, type AnonymizationMatch, type AnonymizationTerm, type ApplyResult, type AutocompleteSuggestionPluginOptions, type AutocompleteSuggestionState, type AutocompleteSuggestionStatus, type AutocompleteTriggerCheck, type AutocompleteTriggerOptions, type AutocompleteTriggerSkipReason, type CreateEmptyDocumentOptions, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, type DeriveBlockIdInput, type DirectiveKind, type DirectiveRange, type Document, type DocxCompatibility, type EmbeddedFont, type EmbeddedFontParts, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditOperation, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAISignatureParty, type FolioBlockId, type ImageMeta, type ImageRef, type MarkdownOptions, type MarkdownResult, type PositionalText, type ResolvedAnchor, type TemplatePreviewSpan, type TemplatePreviewValue, type TemplatePreviewValues, type TemplateSlashMenuKeyAction, type TemplateSlashMenuState, type WordDiffSegment, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applySuggestions, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, deriveBlockId, diffWordSegments, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, isFolioBlockId, isSequentialFolioBlockId, isSuggestionStale, normalizeFolioAIBlockText, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setFocusedSuggestionMeta, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };
+export { type AIBarStatus, type AIChatMode, type AICitation, type AICitationRange, type AICitationSource, type AIGenerateInput, type AISuggestion, type AISuggestionApplyMode, type AISuggestionPreset, type AISuggestionSeverity, type AISuggestionStatus, type AcceptAutocompleteResult, type AnonymizationMatch, type AnonymizationTerm, type ApplyResult, type AutocompleteSuggestionPluginOptions, type AutocompleteSuggestionState, type AutocompleteSuggestionStatus, type AutocompleteTriggerCheck, type AutocompleteTriggerOptions, type AutocompleteTriggerSkipReason, type CreateEmptyDocumentOptions, DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, type DeriveBlockIdInput, type DirectiveKind, type DirectiveRange, type Document, type DocxCompatibility, type EmbeddedFont, type EmbeddedFontParts, type FolioAIBlock, type FolioAIBlockAnchor, type FolioAIBlockKind, type FolioAIBlockPreviewRun, type FolioAIComment, type FolioAIEditAppliedOperation, type FolioAIEditApplyMode, type FolioAIEditApplyResult, type FolioAIEditOperation, type FolioAIEditReviewMeta, type FolioAIEditSeverity, type FolioAIEditSkipReason, type FolioAIEditSkippedOperation, type FolioAIEditSnapshot, type FolioAISignatureParty, type FolioBlockId, type ImageMeta, type ImageRef, type MarkdownOptions, type MarkdownResult, type PositionalText, type ResolvedAnchor, type TemplatePreviewSpan, type TemplatePreviewValue, type TemplatePreviewValues, type TemplateSlashMenuKeyAction, type TemplateSlashMenuState, type WordDiffSegment, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applySuggestions, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, deriveBlockId, diffWordSegments, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, isFolioBlockId, isSequentialFolioBlockId, isSuggestionStale, normalizeFolioAIBlockText, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };

package/dist/index.js

@@ -9,6 +9,7 @@ import { createFolioAIEditSnapshot, hashFolioAIBlockText, normalizeFolioAIBlockT
 import { diffWordSegments } from "./ai-edits/word-diff.js";
 import { applyFolioAIEditOperations } from "./ai-edits/apply.js";
 import { setAISuggestionsMeta, setFocusedSuggestionMeta } from "./prosemirror/plugins/aiSuggestionDecorations.js";
+import { getGoogleFontsEnabled, setGoogleFontsEnabled } from "./utils/fontResolver.js";
 import { scrollFolioPositionIntoView } from "./paged-layout/scrollToPmPosition.js";
 import { getFolioCaretViewportRect, getFolioSelectionViewportRect } from "./paged-layout/selectionViewportRect.js";
 import { createAICitationDecorationsPlugin, setAICitationsMeta, setActiveCitationMeta } from "./prosemirror/plugins/aiCitationDecorations.js";
@@ -20,4 +21,4 @@ import { DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, acceptAutocompleteSuggestion, acc
 import { fromMarkdown } from "./markdown/fromMarkdown.js";
 import { toMarkdown, toMarkdownResult } from "./markdown/index.js";
 import { extractEmbeddedFonts, getEmbeddedFontFaces } from "./fonts/embeddedFonts.js";
-export { DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applySuggestions, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, deriveBlockId, diffWordSegments, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, isFolioBlockId, isSequentialFolioBlockId, isSuggestionStale, normalizeFolioAIBlockText, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setFocusedSuggestionMeta, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };
+export { DEFAULT_AI_SUGGESTION_PRESETS, DEFAULT_AUTOCOMPLETE_DEAD_ZONE_NODES, acceptAutocompleteSuggestion, acceptAutocompleteWord, anonymizationDecorationsKey, appendAutocompleteToken, applyFolioAIEditOperations, applySuggestions, autocompleteSuggestionKey, autocompleteSuggestionPlugin, buildPositionalText, clearAutocompleteSuggestion, clearTemplateSlashMenu, consumeTemplateSlashQuery, createAICitationDecorationsPlugin, createDocx, createEmptyDocument, createFolioAIEditSnapshot, deriveBlockId, diffWordSegments, extractEmbeddedFonts, finishAutocompleteSuggestion, fromMarkdown, getAnonymizationMatches, getAutocompleteSuggestion, getEmbeddedFontFaces, getFolioCaretViewportRect, getFolioParaIdFromBlockId, getFolioSelectionViewportRect, getGoogleFontsEnabled, getTemplateDirectives, getTemplateSlashMenu, hashFolioAIBlockText, isFolioBlockId, isSequentialFolioBlockId, isSuggestionStale, normalizeFolioAIBlockText, resetTemplateSlashQuery, resolveSuggestionAnchor, scanDirectives, scrollFolioPositionIntoView, setAICitationsMeta, setAISuggestionsMeta, setActiveCitationMeta, setAnonymizationTermsMeta, setFocusedSuggestionMeta, setGoogleFontsEnabled, setTemplatePreviewValues, shouldTriggerAutocomplete, startAutocompleteSuggestion, templateSlashMenuKey, toMarkdown, toMarkdownResult };

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): {