@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/cjs/modules/word/security/encryption.js

@@ -0,0 +1,612 @@
+"use strict";
+/**
+ * DOCX Agile Encryption (MS-OFFCRYPTO)
+ *
+ * Implements ECMA-376 Agile Encryption (used by Office 2010+) for encrypted
+ * DOCX files. Encrypted DOCX files use the CFB (Compound File Binary) format
+ * to wrap the ZIP content.
+ *
+ * This module provides:
+ * - Password-based encryption/decryption of DOCX content
+ * - EncryptionInfo XML generation/parsing
+ *
+ * All AES and SHA primitives are delegated to `@utils/crypto`, which uses
+ * synchronous `node:crypto` APIs in Node and Web Crypto in the browser.
+ * The KDF inner loop runs ~100,000 hashes per derived key; on Node we go
+ * through the synchronous fast path so a round-trip completes in well
+ * under a second instead of the multi-second microtask churn that the
+ * old `await crypto.subtle.digest()` loop produced.
+ *
+ * References:
+ *   - MS-OFFCRYPTO: Office Document Cryptography Structure
+ *   - ECMA-376 Part 3: Markup Compatibility and Extensibility
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGILE_BLOCK_KEYS = void 0;
+exports.isEncryptedDocx = isEncryptedDocx;
+exports.deriveEncryptionKey = deriveEncryptionKey;
+exports.verifyPassword = verifyPassword;
+exports.decryptPackage = decryptPackage;
+exports.parseEncryptionInfoXml = parseEncryptionInfoXml;
+exports.decryptDocx = decryptDocx;
+exports.encryptDocx = encryptDocx;
+const crypto_1 = require("../../../utils/crypto.js");
+const internal_utils_1 = require("../core/internal-utils");
+const errors_1 = require("../errors");
+const cfb_reader_1 = require("./cfb-reader");
+/** Detect whether a buffer is an encrypted Office document (CFB format). */
+function isEncryptedDocx(buffer) {
+    // CFB signature: D0CF11E0A1B11AE1
+    if (buffer.length < 8) {
+        return false;
+    }
+    return (buffer[0] === 0xd0 &&
+        buffer[1] === 0xcf &&
+        buffer[2] === 0x11 &&
+        buffer[3] === 0xe0 &&
+        buffer[4] === 0xa1 &&
+        buffer[5] === 0xb1 &&
+        buffer[6] === 0x1a &&
+        buffer[7] === 0xe1);
+}
+/**
+ * Detect whether the platform's `@utils/crypto.hash` supports the requested
+ * algorithm synchronously. Node's implementation accepts every OpenSSL
+ * digest (SHA-1/256/384/512, MD5); the browser implementation only ships
+ * synchronous SHA-256 and MD5 — anything else throws.
+ *
+ * The detection result is cached per algorithm so we only pay the probe
+ * cost once.
+ */
+const _syncHashCache = new Map();
+function canHashSync(algorithm) {
+    const cached = _syncHashCache.get(algorithm);
+    if (cached !== undefined) {
+        return cached;
+    }
+    let ok = false;
+    try {
+        (0, crypto_1.hash)(algorithm, new Uint8Array(0));
+        ok = true;
+    }
+    catch {
+        ok = false;
+    }
+    _syncHashCache.set(algorithm, ok);
+    return ok;
+}
+/**
+ * Derive an encryption key from a password using the agile encryption KDF.
+ *
+ * Per MS-OFFCRYPTO 2.3.4.11:
+ *   H_0 = H(salt + password)
+ *   H_i = H(iterator + H_{i-1})  for i = 0..spinCount-1
+ *   H_final = H(H_{spinCount} + blockKey)
+ *   Key = first keySize bytes of H_final
+ */
+async function deriveEncryptionKey(password, info, blockKey) {
+    const pwdBytes = stringToUtf16LE(password);
+    const hashName = mapHashName(info.hashAlgorithm);
+    // Reusable 4-byte iterator + scratch buffer to avoid per-iteration
+    // allocations inside the spin loop. The scratch holds [iter || H_{i-1}]
+    // and is rebuilt in place.
+    const iterAndPrev = new Uint8Array(4 + getHashSizeFor(hashName));
+    const iterView = new DataView(iterAndPrev.buffer, 0, 4);
+    let h;
+    if (canHashSync(hashName)) {
+        // Fast path: ~100,000 synchronous digests, no microtask churn.
+        h = (0, crypto_1.hash)(hashName, concat(info.keySalt, pwdBytes));
+        for (let i = 0; i < info.spinCount; i++) {
+            iterView.setUint32(0, i, true);
+            iterAndPrev.set(h, 4);
+            h = (0, crypto_1.hash)(hashName, iterAndPrev);
+        }
+        h = (0, crypto_1.hash)(hashName, concat(h, blockKey));
+    }
+    else {
+        // Browser fallback: Web Crypto SHA-1/384/512 are async-only.
+        h = await (0, crypto_1.hashAsync)(hashName, concat(info.keySalt, pwdBytes));
+        for (let i = 0; i < info.spinCount; i++) {
+            iterView.setUint32(0, i, true);
+            iterAndPrev.set(h, 4);
+            h = await (0, crypto_1.hashAsync)(hashName, iterAndPrev);
+        }
+        h = await (0, crypto_1.hashAsync)(hashName, concat(h, blockKey));
+    }
+    // Truncate to keySize. The hash size MUST be at least the requested
+    // key length — otherwise we'd hand the AES layer a short key buffer
+    // that either fails import or produces a key the counterparty can't
+    // validate. Reject misconfigured EncryptionInfo up-front with a clear
+    // error.
+    const keyBytes = info.keyBits / 8;
+    if (h.length < keyBytes) {
+        throw new Error(`deriveEncryptionKey: hash output of ${h.length} bytes is too ` +
+            `short for keyBits=${info.keyBits} (need ${keyBytes}). ` +
+            `Use a hash algorithm with a larger digest size (e.g. SHA-512 ` +
+            `for keyBits ≤ 512).`);
+    }
+    return h.slice(0, keyBytes);
+}
+/** Block keys as defined in MS-OFFCRYPTO 2.3.4.13. */
+exports.AGILE_BLOCK_KEYS = {
+    /** For encrypting verifier hash input. */
+    verifierHashInput: new Uint8Array([0xfe, 0xa7, 0xd2, 0x76, 0x3b, 0x4b, 0x9e, 0x79]),
+    /** For encrypting verifier hash value. */
+    verifierHashValue: new Uint8Array([0xd7, 0xaa, 0x0f, 0x6d, 0x30, 0x61, 0x34, 0x4e]),
+    /** For encrypting the main key. */
+    encryptedKey: new Uint8Array([0x14, 0x6e, 0x0b, 0xe7, 0xab, 0xac, 0xd0, 0xd6]),
+    /** For data integrity HMAC key. */
+    dataIntegrityKey: new Uint8Array([0x5f, 0xb2, 0xad, 0x01, 0x0c, 0xb9, 0xe1, 0xf6]),
+    /** For data integrity HMAC value. */
+    dataIntegrityValue: new Uint8Array([0xa0, 0x67, 0x7f, 0x02, 0xb2, 0x2c, 0x84, 0x33])
+};
+/**
+ * Verify a password against the encryption info.
+ *
+ * @returns True if password is correct.
+ */
+async function verifyPassword(password, info) {
+    try {
+        // Derive verifier hash input key
+        const verifierInputKey = await deriveEncryptionKey(password, info, exports.AGILE_BLOCK_KEYS.verifierHashInput);
+        // Decrypt the verifier hash input (PKCS#7 padded by encryption write path)
+        const verifierInput = aesCbcPkcs7Decrypt(info.encryptedVerifierHashInput, verifierInputKey, info.keySalt);
+        // Hash the verifier input
+        const hashAlg = mapHashName(info.hashAlgorithm);
+        const computedHash = await (0, crypto_1.hashAsync)(hashAlg, verifierInput);
+        // Derive verifier hash value key
+        const verifierValueKey = await deriveEncryptionKey(password, info, exports.AGILE_BLOCK_KEYS.verifierHashValue);
+        // Decrypt the verifier hash value (PKCS#7 padded by encryption write path)
+        const expectedHash = aesCbcPkcs7Decrypt(info.encryptedVerifierHashValue, verifierValueKey, info.keySalt);
+        // Compare (truncate to hashSize in case of padding)
+        return bytesEqual(computedHash.slice(0, info.hashSize), expectedHash.slice(0, info.hashSize));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Decrypt the package data using the password.
+ *
+ * @param encryptedPackage - The EncryptedPackage stream from CFB.
+ * @param info - Agile encryption parameters.
+ * @param password - The user password.
+ * @param maxDecryptedSize - Optional upper bound on the decrypted size; if the
+ *   `totalSize` header claims a larger value, throw rather than allocate.
+ *   Defaults to 512 MiB so adversarial files cannot trigger arbitrary-size
+ *   allocations before security policy is applied at the unzip layer.
+ * @returns The decrypted (unencrypted) package bytes.
+ */
+async function decryptPackage(encryptedPackage, info, password, maxDecryptedSize = 512 * 1024 * 1024) {
+    // Derive key encryption key
+    const keyEncryptionKey = await deriveEncryptionKey(password, info, exports.AGILE_BLOCK_KEYS.encryptedKey);
+    // Decrypt the actual package key (PKCS#7 padded by encryption write path)
+    const packageKey = aesCbcPkcs7Decrypt(info.encryptedKeyValue, keyEncryptionKey, info.keySalt);
+    if (encryptedPackage.length < 8) {
+        throw new errors_1.DocxDecryptionError("EncryptedPackage too small (missing 8-byte size header)");
+    }
+    // First 8 bytes are the total decrypted size (uint64 LE)
+    const totalSizeView = new DataView(encryptedPackage.buffer, encryptedPackage.byteOffset, 8);
+    const totalSize = Number(totalSizeView.getBigUint64(0, true));
+    // Sanity check the declared size: it cannot legally exceed the encrypted
+    // body length, and we refuse to allocate above the configured bound.
+    const encryptedBodyLength = encryptedPackage.length - 8;
+    if (!Number.isFinite(totalSize) ||
+        totalSize < 0 ||
+        totalSize > encryptedBodyLength ||
+        totalSize > maxDecryptedSize) {
+        throw new errors_1.DocxDecryptionError(`EncryptedPackage declared size (${totalSize}) is invalid or exceeds the maximum allowed (${maxDecryptedSize})`);
+    }
+    // Decrypt in 4096-byte segments
+    const segmentSize = 4096;
+    const encData = encryptedPackage.slice(8);
+    const segments = [];
+    const segCount = Math.ceil(encData.length / segmentSize);
+    const hashName = mapHashName(info.hashAlgorithm);
+    const idxBytes = new Uint8Array(4);
+    const idxView = new DataView(idxBytes.buffer);
+    for (let i = 0; i < segCount; i++) {
+        const segStart = i * segmentSize;
+        const segEnd = Math.min(segStart + segmentSize, encData.length);
+        const segData = encData.slice(segStart, segEnd);
+        // Segment IV is hash(salt + segment_index_LE), truncated to block size.
+        idxView.setUint32(0, i, true);
+        const segIv = (await (0, crypto_1.hashAsync)(hashName, concat(info.keySalt, idxBytes))).slice(0, info.blockSize);
+        // Package segments use zero padding (MS-OFFCRYPTO §2.3.4.15). Use the
+        // raw (no-padding) AES-CBC decrypt — never the PKCS#7 path, which
+        // would silently mis-strip valid-looking trailing zeros.
+        segments.push((0, crypto_1.aesCbcDecryptRaw)(segData, packageKey, ivToBlockSize(segIv)));
+    }
+    // Concatenate and truncate to total size
+    const result = new Uint8Array(totalSize);
+    let offset = 0;
+    for (const seg of segments) {
+        const copyLen = Math.min(seg.length, totalSize - offset);
+        result.set(seg.slice(0, copyLen), offset);
+        offset += copyLen;
+        if (offset >= totalSize) {
+            break;
+        }
+    }
+    return result;
+}
+// =============================================================================
+// Internal Crypto Helpers
+//
+// All AES and SHA work is delegated to `@utils/crypto`. Node uses
+// synchronous `node:crypto`, the browser variant uses Web Crypto / pure
+// JS — same API on both sides.
+// =============================================================================
+function mapHashName(name) {
+    const map = {
+        SHA1: "SHA-1",
+        SHA256: "SHA-256",
+        SHA384: "SHA-384",
+        SHA512: "SHA-512"
+    };
+    return map[name] ?? "SHA-512";
+}
+/** Static lookup so the KDF spin loop doesn't pay a per-call cost. */
+function getHashSizeFor(hashName) {
+    switch (hashName) {
+        case "SHA-1":
+            return 20;
+        case "SHA-256":
+            return 32;
+        case "SHA-384":
+            return 48;
+        case "SHA-512":
+            return 64;
+        default:
+            // Conservative upper bound: any reasonable hash output fits in 64 bytes.
+            // Callers that go through this path are misconfigured anyway and will
+            // be rejected by the keyBits sanity check after the first digest.
+            return 64;
+    }
+}
+/**
+ * Decrypt an AES-CBC blob whose plaintext was written with PKCS#7 padding.
+ * Used for the encryptedKeyValue / encryptedVerifierHashInput /
+ * encryptedVerifierHashValue blobs. The IV is truncated/extended to 16
+ * bytes per the OOXML spec.
+ */
+function aesCbcPkcs7Decrypt(data, key, iv) {
+    return (0, crypto_1.aesCbcDecrypt)(data, key, ivToBlockSize(iv));
+}
+/**
+ * Encrypt with AES-CBC + PKCS#7 padding — the Agile spec's standard
+ * choice for verifier blobs and the encrypted package key.
+ */
+function aesCbcPkcs7Encrypt(data, key, iv) {
+    return (0, crypto_1.aesCbcEncrypt)(data, key, ivToBlockSize(iv));
+}
+/**
+ * Encrypt with AES-CBC and zero-padding (no PKCS#7). Used by package
+ * segment encryption: data is already padded to a 16-byte boundary by
+ * the caller, and the on-disk format does not include a PKCS#7 trailer.
+ */
+function aesCbcZeroPadEncrypt(data, key, iv) {
+    return (0, crypto_1.aesCbcEncryptRaw)(data, key, ivToBlockSize(iv));
+}
+/** Truncate or right-pad an IV to the AES block size (16 bytes). */
+function ivToBlockSize(iv) {
+    if (iv.length === 16) {
+        return iv;
+    }
+    const out = new Uint8Array(16);
+    out.set(iv.slice(0, 16));
+    return out;
+}
+function concat(a, b) {
+    const result = new Uint8Array(a.length + b.length);
+    result.set(a, 0);
+    result.set(b, a.length);
+    return result;
+}
+function stringToUtf16LE(s) {
+    const buf = new Uint8Array(s.length * 2);
+    for (let i = 0; i < s.length; i++) {
+        const code = s.charCodeAt(i);
+        buf[i * 2] = code & 0xff;
+        buf[i * 2 + 1] = (code >> 8) & 0xff;
+    }
+    return buf;
+}
+function bytesEqual(a, b) {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let diff = 0;
+    for (let i = 0; i < a.length; i++) {
+        diff |= a[i] ^ b[i];
+    }
+    return diff === 0;
+}
+// =============================================================================
+// EncryptionInfo XML Parser
+// =============================================================================
+/**
+ * Parse an EncryptionInfo XML stream from a CFB-wrapped encrypted DOCX.
+ *
+ * This is the UTF-8 XML part after the 8-byte version/flags header.
+ *
+ * @param xmlStr - The EncryptionInfo XML content.
+ * @returns Parsed agile encryption info.
+ */
+function parseEncryptionInfoXml(xmlStr) {
+    // Simple regex-based extraction for the key <keyEncryptors><keyEncryptor>... element
+    const keyDataMatch = /<keyData\s([\s\S]*?)\/>/.exec(xmlStr);
+    const pwdEncryptorMatch = /<p:encryptedKey\s([\s\S]*?)\/>/.exec(xmlStr);
+    if (!keyDataMatch || !pwdEncryptorMatch) {
+        throw new errors_1.DocxDecryptionError("Invalid EncryptionInfo XML - missing keyData or encryptedKey");
+    }
+    const pwdData = parseAttrs(pwdEncryptorMatch[1]);
+    // Required cryptographic fields — empty/missing values cannot decrypt and
+    // produce confusing CryptoOperation errors downstream. Fail fast with a
+    // clear message instead.
+    const requireField = (name) => {
+        const v = pwdData[name];
+        if (v === undefined || v === "") {
+            throw new errors_1.DocxDecryptionError(`Invalid EncryptionInfo XML - missing or empty required field: ${name}`);
+        }
+        return v;
+    };
+    const keyBitsRaw = parseInt(pwdData.keyBits ?? "256", 10);
+    if (keyBitsRaw !== 128 && keyBitsRaw !== 192 && keyBitsRaw !== 256) {
+        throw new errors_1.DocxDecryptionError(`Unsupported keyBits in EncryptionInfo: ${pwdData.keyBits} (expected 128, 192, or 256)`);
+    }
+    const hashAlgRaw = pwdData.hashAlgorithm ?? "SHA512";
+    if (hashAlgRaw !== "SHA1" &&
+        hashAlgRaw !== "SHA256" &&
+        hashAlgRaw !== "SHA384" &&
+        hashAlgRaw !== "SHA512") {
+        throw new errors_1.DocxDecryptionError(`Unsupported hashAlgorithm in EncryptionInfo: ${hashAlgRaw} (expected SHA1/SHA256/SHA384/SHA512)`);
+    }
+    // Validate numeric fields against sane ranges. EncryptionInfo XML is
+    // parsed straight from the CFB stream of an arbitrary input file, so
+    // every numeric attribute is attacker-controlled. Without bounds
+    // checks:
+    //   - spinCount: a hostile file specifying spinCount=10⁹ would freeze
+    //     the verifier-derivation loop in deriveEncryptionKey.
+    //   - hashSize/blockSize: used as slice lengths and AES IV sizes.
+    //     Outsized values silently produce wrong keys / IVs and obscure
+    //     decryption errors; negative or NaN crashes downstream.
+    // Limits are deliberately wider than what real Office files emit so we
+    // don't reject legitimate documents.
+    const spinCount = parseInt(pwdData.spinCount ?? "100000", 10);
+    if (!Number.isFinite(spinCount) || spinCount < 0 || spinCount > 10000000) {
+        throw new errors_1.DocxDecryptionError(`Invalid spinCount in EncryptionInfo: ${pwdData.spinCount} (expected 0..10_000_000)`);
+    }
+    const hashSize = parseInt(pwdData.hashSize ?? "64", 10);
+    // Largest legitimate hash here is SHA-512 → 64 bytes. Cap at 128 to
+    // accommodate hypothetical extensions while still rejecting crazy values.
+    if (!Number.isFinite(hashSize) || hashSize < 1 || hashSize > 128) {
+        throw new errors_1.DocxDecryptionError(`Invalid hashSize in EncryptionInfo: ${pwdData.hashSize} (expected 1..128)`);
+    }
+    const blockSize = parseInt(pwdData.blockSize ?? "16", 10);
+    // AES is fixed at 16; some tooling emits 8 for legacy ciphers. Anything
+    // outside [8, 64] is bogus.
+    if (!Number.isFinite(blockSize) || blockSize < 8 || blockSize > 64) {
+        throw new errors_1.DocxDecryptionError(`Invalid blockSize in EncryptionInfo: ${pwdData.blockSize} (expected 8..64)`);
+    }
+    return {
+        cipherAlgorithm: "AES",
+        cipherChaining: "ChainingModeCBC",
+        keyBits: keyBitsRaw,
+        hashAlgorithm: hashAlgRaw,
+        hashSize,
+        spinCount,
+        keySalt: (0, internal_utils_1.base64ToBytes)(requireField("saltValue")),
+        encryptedVerifierHashInput: (0, internal_utils_1.base64ToBytes)(requireField("encryptedVerifierHashInput")),
+        encryptedVerifierHashValue: (0, internal_utils_1.base64ToBytes)(requireField("encryptedVerifierHashValue")),
+        encryptedKeyValue: (0, internal_utils_1.base64ToBytes)(requireField("encryptedKeyValue")),
+        blockSize
+    };
+}
+function parseAttrs(str) {
+    const attrs = {};
+    const re = /(\w+)="([^"]*)"/g;
+    let match;
+    while ((match = re.exec(str)) !== null) {
+        attrs[match[1]] = match[2];
+    }
+    return attrs;
+}
+// =============================================================================
+// High-level Encrypted DOCX Reader
+// =============================================================================
+/**
+ * Read an encrypted DOCX file by providing a password.
+ *
+ * Handles the full pipeline:
+ * 1. Parse CFB container
+ * 2. Extract EncryptionInfo and EncryptedPackage streams
+ * 3. Verify password and decrypt
+ * 4. Return the decrypted DOCX ZIP bytes
+ *
+ * @param buffer - The encrypted DOCX file (CFB format).
+ * @param password - The password to decrypt with.
+ * @param maxDecryptedSize - Optional cap on the decrypted size (defaults to 512 MiB).
+ * @returns The decrypted DOCX ZIP bytes (can be passed to readDocx).
+ * @throws Error if the file is not encrypted, password is wrong, or decryption fails.
+ */
+async function decryptDocx(buffer, password, maxDecryptedSize) {
+    if (!isEncryptedDocx(buffer)) {
+        throw new errors_1.DocxDecryptionError("Not an encrypted DOCX file (CFB signature not found)");
+    }
+    // Parse CFB container
+    const entries = (0, cfb_reader_1.readCfb)(buffer);
+    // Find EncryptionInfo stream
+    const _encInfoEntry = entries.find(e => e.name === "EncryptionInfo" || e.name === "\x06DataSpaces");
+    // The actual EncryptionInfo stream
+    const encInfoStream = entries.find(e => e.name === "EncryptionInfo");
+    if (!encInfoStream) {
+        throw new errors_1.DocxDecryptionError("CFB: EncryptionInfo stream not found");
+    }
+    // Find EncryptedPackage stream
+    const encPkgEntry = entries.find(e => e.name === "EncryptedPackage");
+    if (!encPkgEntry) {
+        throw new errors_1.DocxDecryptionError("CFB: EncryptedPackage stream not found");
+    }
+    // Parse EncryptionInfo — first 4 bytes are version major + minor + flags.
+    const infoData = encInfoStream.data;
+    const versionView = new DataView(infoData.buffer, infoData.byteOffset, 4);
+    const versionMajor = versionView.getUint16(0, true);
+    const versionMinor = versionView.getUint16(2, true);
+    // MS-OFFCRYPTO §2.3 distinguishes encryption families primarily by the
+    // (major, minor) pair: Agile is 4.4, Extensible is 4.3, ECMA-376 Standard
+    // Encryption is 4.2, RC4 CryptoAPI is 4.x with minor < 2, etc. We
+    // currently implement only Agile.
+    if (versionMajor === 4 && versionMinor === 4) {
+        // Agile encryption — XML follows after 8 bytes
+        const xmlStr = internal_utils_1.utf8Decoder.decode(infoData.slice(8));
+        const info = parseEncryptionInfoXml(xmlStr);
+        // Verify password
+        const valid = await verifyPassword(password, info);
+        if (!valid) {
+            throw new errors_1.DocxDecryptionError("Incorrect password");
+        }
+        // Decrypt package
+        return decryptPackage(encPkgEntry.data, info, password, maxDecryptedSize);
+    }
+    throw new errors_1.DocxDecryptionError(`Unsupported encryption version: ${versionMajor}.${versionMinor}. ` +
+        `Only Agile Encryption (4.4) is supported.`);
+}
+// =============================================================================
+// Encrypt DOCX
+// =============================================================================
+/**
+ * Encrypt a DOCX ZIP file with a password using Agile Encryption (MS-OFFCRYPTO).
+ *
+ * Produces a CFB (OLE2 Compound File) containing:
+ *   - EncryptionInfo stream (Agile encryption XML)
+ *   - EncryptedPackage stream (segment-encrypted ZIP data)
+ *
+ * The output can be opened by Microsoft Word with the given password.
+ *
+ * @param zipBytes - The unencrypted DOCX content (ZIP format).
+ * @param password - The password to encrypt with.
+ * @param options - Encryption options (key length, hash algorithm, spin count).
+ * @returns The encrypted DOCX as a CFB-formatted Uint8Array.
+ */
+async function encryptDocx(zipBytes, password, options) {
+    const keyBits = options?.keyBits ?? 256;
+    const hashAlgorithm = options?.hashAlgorithm ?? "SHA512";
+    const spinCount = options?.spinCount ?? 100000;
+    const hashName = mapHashName(hashAlgorithm);
+    const hashSize = getHashSizeFor(hashName);
+    const keyBytes = keyBits / 8;
+    const blockSize = 16;
+    // 1. Generate random salt (16 bytes) and package key
+    const keySalt = (0, internal_utils_1.randomBytes)(16);
+    const packageKey = (0, internal_utils_1.randomBytes)(keyBytes);
+    // 2. Generate key encryption key (for encrypting the package key)
+    const keyEncryptionKey = await deriveEncryptionKey(password, { keySalt, spinCount, hashAlgorithm, keyBits }, exports.AGILE_BLOCK_KEYS.encryptedKey);
+    // 3. Encrypt the package key
+    const encryptedKeyValue = aesCbcPkcs7Encrypt(packageKey, keyEncryptionKey, keySalt);
+    // 4. Generate verifier: random 16 bytes, hash them, encrypt both
+    const verifierInput = (0, internal_utils_1.randomBytes)(16);
+    const verifierHash = await (0, crypto_1.hashAsync)(hashName, verifierInput);
+    const verifierInputKey = await deriveEncryptionKey(password, { keySalt, spinCount, hashAlgorithm, keyBits }, exports.AGILE_BLOCK_KEYS.verifierHashInput);
+    const encryptedVerifierHashInput = aesCbcPkcs7Encrypt(verifierInput, verifierInputKey, keySalt);
+    const verifierValueKey = await deriveEncryptionKey(password, { keySalt, spinCount, hashAlgorithm, keyBits }, exports.AGILE_BLOCK_KEYS.verifierHashValue);
+    const encryptedVerifierHashValue = aesCbcPkcs7Encrypt(verifierHash, verifierValueKey, keySalt);
+    // 5. Encrypt the ZIP data in 4096-byte segments
+    const encryptedPackage = await encryptPackageData(zipBytes, packageKey, keySalt, hashName, blockSize);
+    // 6. Generate EncryptionInfo XML
+    const encInfoXml = buildEncryptionInfoXml({
+        keyBits,
+        hashAlgorithm,
+        hashSize,
+        spinCount,
+        blockSize,
+        keySalt,
+        encryptedVerifierHashInput,
+        encryptedVerifierHashValue,
+        encryptedKeyValue
+    });
+    // Prepend 8-byte version header: version 4.4 + flags 0x40
+    const xmlBytes = internal_utils_1.utf8Encoder.encode(encInfoXml);
+    const encInfoStream = new Uint8Array(8 + xmlBytes.length);
+    const encInfoView = new DataView(encInfoStream.buffer);
+    encInfoView.setUint16(0, 4, true); // version major
+    encInfoView.setUint16(2, 4, true); // version minor
+    encInfoView.setUint32(4, 0x40, true); // flags (agile)
+    encInfoStream.set(xmlBytes, 8);
+    // 7. Package into CFB
+    const cfbBytes = (0, cfb_reader_1.writeCfb)([
+        { name: "EncryptionInfo", data: encInfoStream },
+        { name: "EncryptedPackage", data: encryptedPackage }
+    ]);
+    return cfbBytes;
+}
+// =============================================================================
+// Encrypt Helpers
+// =============================================================================
+/**
+ * Encrypt the package data in 4096-byte segments.
+ *
+ * Format: [8 bytes: total size LE uint64] [encrypted segment 0] [encrypted segment 1] ...
+ * Each segment IV = hash(salt + segment_index_LE) truncated to 16 bytes.
+ */
+async function encryptPackageData(data, packageKey, keySalt, hashName, blockSize) {
+    const segmentSize = 4096;
+    const segCount = Math.ceil(data.length / segmentSize);
+    const encSegments = [];
+    const idxBytes = new Uint8Array(4);
+    const idxView = new DataView(idxBytes.buffer);
+    for (let i = 0; i < segCount; i++) {
+        const segStart = i * segmentSize;
+        const segEnd = Math.min(segStart + segmentSize, data.length);
+        let segData = data.slice(segStart, segEnd);
+        // Pad last segment to multiple of blockSize if needed
+        if (segData.length % blockSize !== 0) {
+            const padded = new Uint8Array(Math.ceil(segData.length / blockSize) * blockSize);
+            padded.set(segData);
+            segData = padded;
+        }
+        // Segment IV = hash(salt + segment_index_LE) truncated to blockSize
+        idxView.setUint32(0, i, true);
+        const segIv = (await (0, crypto_1.hashAsync)(hashName, concat(keySalt, idxBytes))).slice(0, blockSize);
+        encSegments.push(aesCbcZeroPadEncrypt(segData, packageKey, segIv));
+    }
+    // Total size (8 bytes LE uint64) + concatenated encrypted segments
+    const totalEncLen = encSegments.reduce((sum, s) => sum + s.length, 0);
+    const result = new Uint8Array(8 + totalEncLen);
+    const sizeView = new DataView(result.buffer);
+    sizeView.setBigUint64(0, BigInt(data.length), true);
+    let offset = 8;
+    for (const seg of encSegments) {
+        result.set(seg, offset);
+        offset += seg.length;
+    }
+    return result;
+}
+/** Build the Agile EncryptionInfo XML document. */
+function buildEncryptionInfoXml(params) {
+    const { keyBits, hashAlgorithm, hashSize, spinCount, blockSize, keySalt, encryptedVerifierHashInput, encryptedVerifierHashValue, encryptedKeyValue } = params;
+    const saltB64 = (0, internal_utils_1.bytesToBase64)(keySalt);
+    const vhiB64 = (0, internal_utils_1.bytesToBase64)(encryptedVerifierHashInput);
+    const vhvB64 = (0, internal_utils_1.bytesToBase64)(encryptedVerifierHashValue);
+    const ekvB64 = (0, internal_utils_1.bytesToBase64)(encryptedKeyValue);
+    return ('<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\r\n' +
+        '<encryption xmlns="http://schemas.microsoft.com/office/2006/encryption" ' +
+        'xmlns:p="http://schemas.microsoft.com/office/2006/keyEncryptor/password" ' +
+        'xmlns:c="http://schemas.microsoft.com/office/2006/keyEncryptor/certificate">\r\n' +
+        `<keyData saltSize="16" blockSize="${blockSize}" keyBits="${keyBits}" ` +
+        `hashSize="${hashSize}" cipherAlgorithm="AES" cipherChaining="ChainingModeCBC" ` +
+        `hashAlgorithm="${hashAlgorithm}" saltValue="${saltB64}"/>\r\n` +
+        '<dataIntegrity encryptedHmacKey="" encryptedHmacValue=""/>\r\n' +
+        "<keyEncryptors>\r\n" +
+        '<keyEncryptor uri="http://schemas.microsoft.com/office/2006/keyEncryptor/password">\r\n' +
+        `<p:encryptedKey spinCount="${spinCount}" saltSize="16" blockSize="${blockSize}" ` +
+        `keyBits="${keyBits}" hashSize="${hashSize}" cipherAlgorithm="AES" ` +
+        `cipherChaining="ChainingModeCBC" hashAlgorithm="${hashAlgorithm}" ` +
+        `saltValue="${saltB64}" ` +
+        `encryptedVerifierHashInput="${vhiB64}" ` +
+        `encryptedVerifierHashValue="${vhvB64}" ` +
+        `encryptedKeyValue="${ekvB64}"/>\r\n` +
+        "</keyEncryptor>\r\n" +
+        "</keyEncryptors>\r\n" +
+        "</encryption>");
+}