mixdog 1.3.3 → 1.3.5

package/src/runtime/office/pdf/cfb-fixture.mjs

@@ -0,0 +1,328 @@
+// A minimal Compound File Binary ([MS-CFB]) writer for tests: real container structure (header, FAT, DIFAT, mini
+// FAT, mini stream, directory with sibling trees), laid out the way Office writes it.
+import { createCipheriv, createHash, createHmac, randomBytes } from 'node:crypto';
+
+const END_OF_CHAIN = 0xfffffffe;
+const FAT_SECTOR = 0xfffffffd;
+const DIFAT_SECTOR = 0xfffffffc;
+const NO_STREAM = 0xffffffff;
+const MINI_SECTOR_SIZE = 64;
+const MINI_STREAM_CUTOFF = 4096;
+const HEADER_DIFAT_ENTRIES = 109;
+
+/**
+ * Entries under the root storage: `{ name, data }` is a stream, `{ name, children }` a storage of further entries.
+ * `version` is the CFB major version: 3 (512-byte sectors) or 4 (4096-byte sectors).
+ */
+export function buildCfb(entries, { version = 3 } = {}) {
+  const sectorSize = version === 4 ? 4096 : 512;
+  const entriesPerSector = sectorSize / 4;
+  const root = { name: 'Root Entry', type: 5, children: entries };
+
+  // Directory ids in storage order, root first; the siblings under each storage form one balanced tree.
+  const nodes = [];
+  const register = (node) => {
+    node.id = nodes.length;
+    nodes.push(node);
+    for (const child of node.children ?? []) register(child);
+  };
+  register(root);
+  const link = (siblings) => {
+    const ordered = [...siblings].sort(
+      (a, b) => a.name.length - b.name.length || (a.name.toUpperCase() < b.name.toUpperCase() ? -1 : 1)
+    );
+    const build = (low, high) => {
+      if (low > high) return NO_STREAM;
+      const middle = (low + high) >> 1;
+      const node = ordered[middle];
+      node.left = build(low, middle - 1);
+      node.right = build(middle + 1, high);
+      return node.id;
+    };
+    return build(0, ordered.length - 1);
+  };
+  for (const node of nodes) {
+    node.left ??= NO_STREAM;
+    node.right ??= NO_STREAM;
+    node.type ??= node.children ? 1 : 2;
+    if (node.children) node.child = link(node.children);
+  }
+
+  const sectors = [];
+  const fat = [];
+  const allocate = (bytes) => {
+    const count = Math.ceil(bytes.length / sectorSize);
+    const start = sectors.length;
+    for (let i = 0; i < count; i++) {
+      const sector = Buffer.alloc(sectorSize);
+      bytes.copy(sector, 0, i * sectorSize, (i + 1) * sectorSize);
+      sectors.push(sector);
+      fat.push(i === count - 1 ? END_OF_CHAIN : sectors.length);
+    }
+    return count ? start : END_OF_CHAIN;
+  };
+
+  const miniStreams = [];
+  const miniFat = [];
+  for (const node of nodes) {
+    if (node.type !== 2) continue;
+    node.size = node.data.length;
+    if (node.size >= MINI_STREAM_CUTOFF) {
+      node.start = allocate(node.data);
+    } else if (node.size === 0) {
+      node.start = END_OF_CHAIN;
+    } else {
+      const count = Math.ceil(node.size / MINI_SECTOR_SIZE);
+      node.start = miniFat.length;
+      for (let i = 0; i < count; i++) miniFat.push(i === count - 1 ? END_OF_CHAIN : miniFat.length + 1);
+      miniStreams.push(Buffer.concat([node.data, Buffer.alloc(count * MINI_SECTOR_SIZE - node.size)]));
+    }
+  }
+  const miniStream = Buffer.concat(miniStreams);
+  root.size = miniStream.length;
+  root.start = allocate(miniStream);
+
+  const miniFatBytes = Buffer.alloc(Math.ceil(miniFat.length / entriesPerSector) * entriesPerSector * 4, 0xff);
+  miniFat.forEach((next, i) => {
+    miniFatBytes.writeUInt32LE(next, i * 4);
+  });
+  const miniFatStart = allocate(miniFatBytes);
+
+  const directoryBytes = Buffer.alloc(Math.ceil(nodes.length / (sectorSize / 128)) * sectorSize);
+  directoryBytes.fill(0xff, 0, directoryBytes.length);
+  nodes.forEach((node, i) => {
+    const at = i * 128;
+    directoryBytes.fill(0, at, at + 128);
+    directoryBytes.write(node.name, at, 'utf16le');
+    directoryBytes.writeUInt16LE((node.name.length + 1) * 2, at + 64);
+    directoryBytes[at + 66] = node.type;
+    directoryBytes[at + 67] = 1;
+    directoryBytes.writeUInt32LE(node.left, at + 68);
+    directoryBytes.writeUInt32LE(node.right, at + 72);
+    directoryBytes.writeUInt32LE(node.child ?? NO_STREAM, at + 76);
+    directoryBytes.writeUInt32LE(node.start ?? 0, at + 116);
+    directoryBytes.writeUInt32LE(node.size ?? 0, at + 120);
+  });
+  // Entries past the last one are unallocated: type 0, with every id unset.
+  for (let at = nodes.length * 128; at < directoryBytes.length; at += 128) directoryBytes.fill(0, at, at + 68);
+  const directoryStart = allocate(directoryBytes);
+
+  // The FAT describes every sector including its own and the DIFAT's, so their counts settle together.
+  let fatCount = 0;
+  let difatCount = 0;
+  while (fatCount * entriesPerSector < fat.length + fatCount + difatCount) {
+    fatCount++;
+    difatCount =
+      fatCount > HEADER_DIFAT_ENTRIES ? Math.ceil((fatCount - HEADER_DIFAT_ENTRIES) / (entriesPerSector - 1)) : 0;
+  }
+  const fatSectorIds = Array.from({ length: fatCount }, (_, i) => sectors.length + i);
+  const difatSectorIds = Array.from({ length: difatCount }, (_, i) => sectors.length + fatCount + i);
+  const fatEntries = [...fat, ...fatSectorIds.map(() => FAT_SECTOR), ...difatSectorIds.map(() => DIFAT_SECTOR)];
+  const fatBytes = Buffer.alloc(fatCount * sectorSize, 0xff);
+  fatEntries.forEach((next, i) => {
+    fatBytes.writeUInt32LE(next, i * 4);
+  });
+  for (let i = 0; i < fatCount; i++) sectors.push(fatBytes.subarray(i * sectorSize, (i + 1) * sectorSize));
+  const beyondHeader = fatSectorIds.slice(HEADER_DIFAT_ENTRIES);
+  for (let i = 0; i < difatCount; i++) {
+    const sector = Buffer.alloc(sectorSize, 0xff);
+    beyondHeader.slice(i * (entriesPerSector - 1), (i + 1) * (entriesPerSector - 1)).forEach((id, j) => {
+      sector.writeUInt32LE(id, j * 4);
+    });
+    sector.writeUInt32LE(i === difatCount - 1 ? END_OF_CHAIN : difatSectorIds[i + 1], sectorSize - 4);
+    sectors.push(sector);
+  }
+
+  const header = Buffer.alloc(sectorSize);
+  Buffer.from([0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]).copy(header, 0);
+  header.writeUInt16LE(0x3e, 24);
+  header.writeUInt16LE(version, 26);
+  header.writeUInt16LE(0xfffe, 28);
+  header.writeUInt16LE(version === 4 ? 12 : 9, 30);
+  header.writeUInt16LE(6, 32);
+  header.writeUInt32LE(version === 4 ? directoryBytes.length / sectorSize : 0, 40);
+  header.writeUInt32LE(fatCount, 44);
+  header.writeUInt32LE(directoryStart, 48);
+  header.writeUInt32LE(MINI_STREAM_CUTOFF, 56);
+  header.writeUInt32LE(miniFatStart, 60);
+  header.writeUInt32LE(miniFatBytes.length / sectorSize, 64);
+  header.writeUInt32LE(difatCount ? difatSectorIds[0] : END_OF_CHAIN, 68);
+  header.writeUInt32LE(difatCount, 72);
+  header.fill(0xff, 76, 512);
+  fatSectorIds.slice(0, HEADER_DIFAT_ENTRIES).forEach((id, i) => {
+    header.writeUInt32LE(id, 76 + i * 4);
+  });
+  return Buffer.concat([header, ...sectors]);
+}
+
+/** The root-level streams of an encrypted OOXML document ([MS-OFFCRYPTO] 2.3.4), with the given ciphertext size. */
+export function encryptedOoxmlEntries(packageBytes = 5000) {
+  return [
+    { name: 'EncryptionInfo', data: Buffer.from([4, 0, 4, 0, 0x40, 0, 0, 0, ...Buffer.from('<encryption/>')]) },
+    { name: 'EncryptedPackage', data: Buffer.concat([Buffer.alloc(8), Buffer.alloc(packageBytes, 0x5a)]) },
+    {
+      name: '\u0006DataSpaces',
+      children: [
+        { name: 'Version', data: Buffer.alloc(76) },
+        { name: 'DataSpaceMap', data: Buffer.alloc(112) },
+      ],
+    },
+  ];
+}
+
+const sha = (algorithm, ...parts) => {
+  const digest = createHash(algorithm);
+  for (const part of parts) digest.update(part);
+  return digest.digest();
+};
+const le32 = (value) => {
+  const bytes = Buffer.alloc(4);
+  bytes.writeUInt32LE(value, 0);
+  return bytes;
+};
+const padTo = (bytes, block) => Buffer.concat([bytes, Buffer.alloc((block - (bytes.length % block)) % block)]);
+const aes = (mode, key, iv, data) => {
+  const cipher = createCipheriv(`aes-${key.length * 8}-${mode}`, key, iv);
+  cipher.setAutoPadding(false);
+  return Buffer.concat([cipher.update(data), cipher.final()]);
+};
+const spun = (algorithm, salt, password, count) => {
+  let value = sha(algorithm, salt, Buffer.from(password, 'utf16le'));
+  for (let i = 0; i < count; i++) value = sha(algorithm, le32(i), value);
+  return value;
+};
+const withSize = (plain, ciphertext) => {
+  const size = Buffer.alloc(8);
+  size.writeBigUInt64LE(BigInt(plain.length), 0);
+  return Buffer.concat([size, ciphertext]);
+};
+
+// 2.3.4.10 HashAlgorithm values the fixture writes, with their OpenSSL names.
+const AGILE_HASHES = { 'SHA-1': 'sha1', SHA1: 'sha1', SHA256: 'sha256', SHA384: 'sha384', SHA512: 'sha512' };
+// Truncated to, or padded with 0x36 up to, `length` bytes (2.3.4.11, 2.3.4.12).
+const fitted = (bytes, length) =>
+  bytes.length >= length
+    ? bytes.subarray(0, length)
+    : Buffer.concat([bytes, Buffer.alloc(length - bytes.length, 0x36)]);
+
+/**
+ * The root-level streams of `plain` encrypted with `password` the way Office writes it, following [MS-OFFCRYPTO]
+ * in the encrypting direction: agile encryption (2.3.4.10–2.3.4.15, AES-256-CBC, SHA-512 or `hashAlgorithm`) by
+ * default, or standard encryption (2.3.4.5–2.3.4.9, AES-128-ECB, SHA-1). `spinCount` is lowered for agile tests to
+ * keep them fast. The keyData salt is `keySaltSize` bytes. Agile encryption carries dataIntegrity (2.3.4.14) unless
+ * `integrity` is false, its HMAC key a salt of `hmacSaltSize` bytes: hashSize, as Excel writes it, unless given.
+ */
+export function encryptOoxmlEntries(
+  plain,
+  password,
+  {
+    scheme = 'agile',
+    spinCount = 1000,
+    hashAlgorithm = 'SHA512',
+    keySaltSize = 16,
+    integrity = true,
+    hmacSaltSize,
+  } = {}
+) {
+  let encryptionInfo;
+  let encryptedPackage;
+  if (scheme === 'agile') {
+    const algorithm = AGILE_HASHES[hashAlgorithm];
+    const hashSize = sha(algorithm).length;
+    const secret = randomBytes(32);
+    const keySalt = randomBytes(keySaltSize);
+    const passwordSalt = randomBytes(16);
+    const hashed = spun(algorithm, passwordSalt, password, spinCount);
+    const keyFor = (block) => fitted(sha(algorithm, hashed, Buffer.from(block)), 32);
+    const verifierInput = randomBytes(16);
+    const encrypted = (block, data) => aes('cbc', keyFor(block), passwordSalt, padTo(data, 16)).toString('base64');
+    const segments = [];
+    for (let offset = 0, index = 0; offset < plain.length; offset += 4096, index++) {
+      const iv = fitted(sha(algorithm, keySalt, le32(index)), 16);
+      segments.push(aes('cbc', secret, iv, padTo(plain.subarray(offset, offset + 4096), 16)));
+    }
+    encryptedPackage = withSize(plain, Buffer.concat(segments));
+    // 2.3.4.14: an HMAC of the whole stream keyed by a random salt, both encrypted with the package key.
+    const sealed = (block, data) =>
+      aes('cbc', secret, fitted(sha(algorithm, keySalt, Buffer.from(block)), 16), padTo(data, 16)).toString('base64');
+    const hmacSalt = randomBytes(hmacSaltSize ?? hashSize);
+    const hmac = createHmac(algorithm, hmacSalt).update(encryptedPackage).digest();
+    const dataIntegrity = integrity
+      ? `<dataIntegrity encryptedHmacKey="${sealed([0x5f, 0xb2, 0xad, 0x01, 0x0c, 0xb9, 0xe1, 0xf6], hmacSalt)}"` +
+        ` encryptedHmacValue="${sealed([0xa0, 0x67, 0x7f, 0x02, 0xb2, 0x2c, 0x84, 0x33], hmac)}"/>`
+      : '';
+    const cipher = `blockSize="16" keyBits="256" hashSize="${hashSize}" cipherAlgorithm="AES" cipherChaining="ChainingModeCBC" hashAlgorithm="${hashAlgorithm}"`;
+    const xml =
+      `<?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">` +
+      `<keyData saltSize="${keySaltSize}" ${cipher} saltValue="${keySalt.toString('base64')}"/>` +
+      dataIntegrity +
+      `<keyEncryptors><keyEncryptor uri="http://schemas.microsoft.com/office/2006/keyEncryptor/password">` +
+      `<p:encryptedKey spinCount="${spinCount}" saltSize="16" ${cipher} saltValue="${passwordSalt.toString('base64')}"` +
+      ` encryptedVerifierHashInput="${encrypted([0xfe, 0xa7, 0xd2, 0x76, 0x3b, 0x4b, 0x9e, 0x79], verifierInput)}"` +
+      ` encryptedVerifierHashValue="${encrypted([0xd7, 0xaa, 0x0f, 0x6d, 0x30, 0x61, 0x34, 0x4e], sha(algorithm, verifierInput))}"` +
+      ` encryptedKeyValue="${encrypted([0x14, 0x6e, 0x0b, 0xe7, 0xab, 0xac, 0xd0, 0xd6], secret)}"/>` +
+      `</keyEncryptor></keyEncryptors></encryption>`;
+    encryptionInfo = Buffer.concat([Buffer.from([4, 0, 4, 0, 0x40, 0, 0, 0]), Buffer.from(xml, 'utf8')]);
+  } else {
+    const salt = randomBytes(16);
+    const final = sha('sha1', spun('sha1', salt, password, 50_000), le32(0));
+    const derive = (fill) => {
+      const buffer = Buffer.alloc(64, fill);
+      for (let i = 0; i < final.length; i++) buffer[i] ^= final[i];
+      return sha('sha1', buffer);
+    };
+    const key = Buffer.concat([derive(0x36), derive(0x5c)]).subarray(0, 16);
+    const verifier = randomBytes(16);
+    const csp = Buffer.from('Microsoft Enhanced RSA and AES Cryptographic Provider\0', 'utf16le');
+    const header = Buffer.concat([...[0x24, 0, 0x660e, 0x8004, 128, 0x18, 0, 0].map(le32), csp]);
+    encryptionInfo = Buffer.concat([
+      Buffer.from([3, 0, 2, 0]),
+      le32(0x24),
+      le32(header.length),
+      header,
+      le32(16),
+      salt,
+      aes('ecb', key, null, verifier),
+      le32(20),
+      aes('ecb', key, null, padTo(sha('sha1', verifier), 16)),
+    ]);
+    encryptedPackage = withSize(plain, aes('ecb', key, null, padTo(plain, 16)));
+  }
+  return [
+    { name: 'EncryptionInfo', data: encryptionInfo },
+    { name: 'EncryptedPackage', data: encryptedPackage },
+    {
+      name: '\u0006DataSpaces',
+      children: [
+        { name: 'Version', data: Buffer.alloc(76) },
+        { name: 'DataSpaceMap', data: Buffer.alloc(112) },
+      ],
+    },
+  ];
+}
+
+/** A binary Word document's "WordDocument" stream whose FibBase ([MS-DOC] 2.5.1) has fEncrypted set or clear. */
+export function wordDocumentStream(encrypted) {
+  const data = Buffer.alloc(6000, 3);
+  data.writeUInt16LE(0xa5ec, 0);
+  data.writeUInt16LE(0x00c1, 2);
+  data.writeUInt16LE(encrypted ? 0x0100 | 0x0200 : 0x0200, 10);
+  return { name: 'WordDocument', data };
+}
+
+/** A "Current User" stream holding a CurrentUserAtom ([MS-PPT] 2.3.2) with this headerToken. */
+export function currentUserStream(headerToken, userName = 'Mixdog') {
+  const name = Buffer.from(userName, 'latin1');
+  const atom = Buffer.alloc(28 + name.length + 4);
+  atom.writeUInt16LE(0x0ff6, 2);
+  atom.writeUInt32LE(atom.length - 8, 4);
+  atom.writeUInt32LE(0x14, 8);
+  atom.writeUInt32LE(headerToken, 12);
+  atom.writeUInt16LE(name.length, 20);
+  atom.writeUInt16LE(0x03f4, 22);
+  atom[24] = 3;
+  name.copy(atom, 28);
+  atom.writeUInt32LE(8, 28 + name.length);
+  return { name: 'Current User', data: atom };
+}

package/src/runtime/office/pdf/cfb-protection.mjs

@@ -0,0 +1,311 @@
+// Password protection, read from the Compound File Binary container itself.
+//
+// An encrypted Office document is a CFB container ([MS-CFB]) whose root storage holds well-known streams. The CFB
+// signature alone proves nothing (an unencrypted legacy .doc renamed .docx has it too), so the root-level stream
+// names are listed the way [MS-CFB] lays them out: the header (2.2), the FAT (2.3) and DIFAT (2.5) to follow the
+// directory sector chain, the directory entries (2.6.1, 2.6.2) and the sibling tree under the root (2.6.4). Only the
+// header, the directory sectors and at most one 64-byte slice of one stream are read, never the whole file. Any
+// malformed or truncated container is "not protected", and the renderer then decides exactly as it would have.
+//
+// The file is untrusted: every count and size it declares is checked against its real length before it is used,
+// every sector chain is walked with a record of the sectors it visited (a sector seen twice is a cycle, and the
+// container malformed), and no walk ever goes past a fixed number of sectors, whatever the file declares.
+import { open } from 'node:fs/promises';
+
+const SIGNATURE = Buffer.from([0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1]);
+const HEADER_SIZE = 512;
+const HEADER_DIFAT_ENTRIES = 109;
+const DIRECTORY_ENTRY_SIZE = 128;
+const MINI_SECTOR_SIZE = 64;
+// [MS-CFB] 2.2: the mini stream cutoff MUST be 4096 bytes.
+const MINI_STREAM_CUTOFF = 4096;
+const MAX_REGULAR_SECTOR = 0xfffffffa;
+const END_OF_CHAIN = 0xfffffffe;
+const NO_STREAM = 0xffffffff;
+const ENTRY_STREAM = 2;
+const ENTRY_ROOT_STORAGE = 5;
+const MAX_DIRECTORY_BYTES = 1024 * 1024;
+// Beyond this an encrypted package is not unlocked for a preview (it is decrypted in memory).
+const MAX_ENCRYPTION_INFO_BYTES = 64 * 1024;
+const MAX_ENCRYPTED_PACKAGE_BYTES = 256 * 1024 * 1024;
+// The most sectors any one chain walk visits: the 512-byte sectors of the largest stream ever read.
+const MAX_CHAIN_SECTORS = MAX_ENCRYPTED_PACKAGE_BYTES / 512;
+
+async function readExactly(handle, position, length) {
+  const buffer = Buffer.alloc(length);
+  const { bytesRead } = await handle.read(buffer, 0, length, position);
+  if (bytesRead !== length) throw new Error('truncated compound file');
+  return buffer;
+}
+
+// Stream names are compared case-insensitively by uppercase mapping ([MS-CFB] 2.6.4), so they are keyed uppercase.
+const streamKey = (name) => name.toUpperCase();
+
+async function openCompoundFile(handle) {
+  const header = await readExactly(handle, 0, HEADER_SIZE);
+  const majorVersion = header.readUInt16LE(26);
+  const sectorShift = header.readUInt16LE(30);
+  if (
+    !header.subarray(0, SIGNATURE.length).equals(SIGNATURE) ||
+    header.readUInt16LE(28) !== 0xfffe ||
+    sectorShift !== { 3: 9, 4: 12 }[majorVersion] ||
+    header.readUInt16LE(32) !== 6 ||
+    header.readUInt32LE(56) !== MINI_STREAM_CUTOFF
+  ) {
+    throw new Error('not a compound file');
+  }
+  const sectorSize = 1 << sectorShift;
+  const entriesPerSector = sectorSize / 4;
+  // Sector n starts at byte (n + 1) * sectorSize, after the header sector; a last partial sector still counts.
+  const sectorsInFile = Math.max(0, Math.ceil((await handle.stat()).size / sectorSize) - 1);
+  const fatSectorCount = header.readUInt32LE(44);
+  const miniFatSectorCount = header.readUInt32LE(64);
+  const difatSectorCount = header.readUInt32LE(72);
+  // A count of sectors larger than the file has sectors is false.
+  if (Math.max(fatSectorCount, miniFatSectorCount, difatSectorCount) > sectorsInFile) {
+    throw new Error('sector counts beyond the file');
+  }
+
+  const readSector = (sector, offset, length) => {
+    if (sector > MAX_REGULAR_SECTOR || sector >= sectorsInFile) throw new Error('sector number out of range');
+    return readExactly(handle, (sector + 1) * sectorSize + offset, length);
+  };
+
+  // The DIFAT sector chain (2.5), followed lazily through the last entry of each of its sectors.
+  const difatSectors = [];
+  const difatSeen = new Set();
+  async function difatSector(hop) {
+    if (hop >= Math.min(difatSectorCount, MAX_CHAIN_SECTORS)) throw new Error('sector beyond the DIFAT');
+    while (difatSectors.length <= hop) {
+      const sector = difatSectors.length
+        ? (await readSector(difatSectors.at(-1), (entriesPerSector - 1) * 4, 4)).readUInt32LE(0)
+        : header.readUInt32LE(68);
+      if (difatSeen.has(sector)) throw new Error('cyclic DIFAT chain');
+      difatSeen.add(sector);
+      difatSectors.push(sector);
+    }
+    return difatSectors[hop];
+  }
+
+  // Location of the index-th FAT sector: the first 109 are in the header, the rest in the DIFAT sector chain (2.5).
+  async function fatSectorLocation(index) {
+    if (index >= fatSectorCount) throw new Error('sector beyond the FAT');
+    if (index < HEADER_DIFAT_ENTRIES) return header.readUInt32LE(76 + index * 4);
+    const perDifatSector = entriesPerSector - 1;
+    const past = index - HEADER_DIFAT_ENTRIES;
+    const sector = await difatSector(Math.floor(past / perDifatSector));
+    return (await readSector(sector, (past % perDifatSector) * 4, 4)).readUInt32LE(0);
+  }
+
+  // A whole stream walks one FAT entry per sector, so each FAT sector is read once and kept.
+  const fatSectors = new Map();
+  async function nextSector(sector) {
+    const index = Math.floor(sector / entriesPerSector);
+    let fat = fatSectors.get(index);
+    if (!fat) {
+      fat = await readSector(await fatSectorLocation(index), 0, sectorSize);
+      fatSectors.set(index, fat);
+    }
+    return fat.readUInt32LE((sector % entriesPerSector) * 4);
+  }
+
+  // A sector chain from `first`, followed lazily and remembered: `chain(n)` is its n-th sector, or null past its
+  // end. A chain longer than `limit` sectors (or MAX_CHAIN_SECTORS), one that leaves the file, or one that comes
+  // back to a sector it already visited is malformed.
+  function sectorChain(first, limit) {
+    const sectors = [];
+    const seen = new Set();
+    let ended = false;
+    return async (index) => {
+      while (sectors.length <= index) {
+        if (ended) return null;
+        const sector = sectors.length ? await nextSector(sectors.at(-1)) : first;
+        if (sector === END_OF_CHAIN) {
+          ended = true;
+          return null;
+        }
+        if (sector > MAX_REGULAR_SECTOR || sector >= sectorsInFile) throw new Error('sector outside the file');
+        if (seen.has(sector)) throw new Error('cyclic sector chain');
+        if (sectors.length >= Math.min(limit, MAX_CHAIN_SECTORS)) throw new Error('sector chain too long');
+        seen.add(sector);
+        sectors.push(sector);
+      }
+      return sectors[index];
+    };
+  }
+
+  const directoryParts = [];
+  const directorySectors = sectorChain(header.readUInt32LE(48), MAX_DIRECTORY_BYTES / sectorSize);
+  for (
+    let sector = await directorySectors(0);
+    sector !== null;
+    sector = await directorySectors(directoryParts.length)
+  ) {
+    directoryParts.push(await readSector(sector, 0, sectorSize));
+  }
+  const directory = Buffer.concat(directoryParts);
+
+  function entryAt(id) {
+    const at = id * DIRECTORY_ENTRY_SIZE;
+    if (at + DIRECTORY_ENTRY_SIZE > directory.length) throw new Error('directory entry out of range');
+    const nameBytes = directory.readUInt16LE(at + 64);
+    if (nameBytes > 64) throw new Error('directory entry name too long');
+    return {
+      name: streamKey(directory.toString('utf16le', at, at + Math.max(nameBytes - 2, 0))),
+      type: directory[at + 66],
+      left: directory.readUInt32LE(at + 68),
+      right: directory.readUInt32LE(at + 72),
+      child: directory.readUInt32LE(at + 76),
+      start: directory.readUInt32LE(at + 116),
+      // Version 3 files may leave the high half of the size uninitialized; it is ignored there.
+      size: majorVersion === 3 ? directory.readUInt32LE(at + 120) : Number(directory.readBigUInt64LE(at + 120)),
+    };
+  }
+
+  const root = entryAt(0);
+  if (root.type !== ENTRY_ROOT_STORAGE) throw new Error('missing root storage');
+  // Only the siblings directly under the root: a storage's own children are never followed.
+  const streams = new Map();
+  const visited = new Set();
+  const pending = [root.child];
+  while (pending.length) {
+    const id = pending.pop();
+    if (id === NO_STREAM) continue;
+    if (visited.has(id)) throw new Error('cyclic directory tree');
+    visited.add(id);
+    const entry = entryAt(id);
+    if (entry.type === ENTRY_STREAM) streams.set(entry.name, entry);
+    pending.push(entry.left, entry.right);
+  }
+
+  // The mini stream ([MS-CFB] 2.6.2) is the root entry's own stream: root.size bytes, which cannot be more than the
+  // file holds, in a regular sector chain followed lazily and shared by every read.
+  let miniStreamSectors = null;
+  async function readMiniStream(offset, length) {
+    // Nothing past the root entry's size is stream data. A read never crosses a sector: mini sectors are 64-byte
+    // aligned and a read is at most one of them.
+    if (offset + length > root.size) throw new Error('mini stream too short');
+    if (root.size > sectorsInFile * sectorSize) throw new Error('mini stream larger than the file');
+    miniStreamSectors ??= sectorChain(root.start, Math.ceil(root.size / sectorSize));
+    const sector = await miniStreamSectors(Math.floor(offset / sectorSize));
+    if (sector === null) throw new Error('mini stream sector missing');
+    return readSector(sector, offset % sectorSize, length);
+  }
+
+  // The mini FAT (header offset 60, at most miniFatSectorCount sectors) maps each mini sector to the next one.
+  let miniFatSectors = null;
+  async function nextMiniSector(mini) {
+    miniFatSectors ??= sectorChain(header.readUInt32LE(60), miniFatSectorCount);
+    const sector = await miniFatSectors(Math.floor(mini / entriesPerSector));
+    if (sector === null) throw new Error('mini FAT too short');
+    return (await readSector(sector, (mini % entriesPerSector) * 4, 4)).readUInt32LE(0);
+  }
+
+  return {
+    hasStream: (name) => streams.has(streamKey(name)),
+    // The first `length` (at most 64) bytes of a root-level stream. A stream under the mini-stream cutoff lives in
+    // the root entry's mini stream ([MS-CFB] 2.6.2), whose mini sector `start` sits at a 64-byte multiple.
+    async readStreamHead(name, length) {
+      const entry = streams.get(streamKey(name));
+      if (!entry || entry.size < length) throw new Error('stream missing or too short');
+      if (entry.size >= MINI_STREAM_CUTOFF) return readSector(entry.start, 0, length);
+      return readMiniStream(entry.start * MINI_SECTOR_SIZE, length);
+    },
+    // A whole root-level stream of at most `maxBytes`. Regular sectors are read in contiguous runs; a stream under
+    // the cutoff follows its mini FAT chain through the root entry's mini stream ([MS-CFB] 2.3), each mini sector
+    // once.
+    async readStream(name, maxBytes) {
+      const entry = streams.get(streamKey(name));
+      if (!entry || entry.size > maxBytes) throw new Error('stream missing or too large');
+      if (entry.size >= MINI_STREAM_CUTOFF) {
+        const sectorCount = Math.ceil(entry.size / sectorSize);
+        const chain = sectorChain(entry.start, sectorCount);
+        const parts = [];
+        let run = null;
+        for (let index = 0; index < sectorCount; index++) {
+          const sector = await chain(index);
+          if (sector === null) throw new Error('stream shorter than its size');
+          if (run && sector === run.first + run.count) run.count++;
+          else {
+            run = { first: sector, count: 1 };
+            parts.push(run);
+          }
+        }
+        const data = Buffer.concat(
+          await Promise.all(parts.map((part) => readSector(part.first, 0, part.count * sectorSize)))
+        );
+        return data.subarray(0, entry.size);
+      }
+      const miniCount = Math.ceil(entry.size / MINI_SECTOR_SIZE);
+      const parts = [];
+      const seen = new Set();
+      let mini = entry.start;
+      for (let index = 0; index < miniCount; index++) {
+        if (index) mini = await nextMiniSector(mini);
+        if (seen.has(mini)) throw new Error('cyclic mini sector chain');
+        seen.add(mini);
+        parts.push(await readMiniStream(mini * MINI_SECTOR_SIZE, MINI_SECTOR_SIZE));
+      }
+      return Buffer.concat(parts).subarray(0, entry.size);
+    },
+  };
+}
+
+async function inspectCompoundFile(path, decide, fallback = false) {
+  let handle;
+  try {
+    handle = await open(path, 'r');
+    return await decide(await openCompoundFile(handle));
+  } catch {
+    return fallback;
+  } finally {
+    await handle?.close();
+  }
+}
+
+/**
+ * The \EncryptionInfo and \EncryptedPackage streams of an encrypted OOXML document ([MS-OFFCRYPTO] 2.3.4.4,
+ * 2.3.4.5), or null when the container cannot be read or the package is too large to unlock.
+ */
+export const readEncryptedOoxml = (path) =>
+  inspectCompoundFile(
+    path,
+    async (file) => ({
+      encryptionInfo: await file.readStream('EncryptionInfo', MAX_ENCRYPTION_INFO_BYTES),
+      encryptedPackage: await file.readStream('EncryptedPackage', MAX_ENCRYPTED_PACKAGE_BYTES),
+    }),
+    null
+  );
+
+/** Only the \EncryptionInfo stream, enough to tell whether the encryption is one a preview can unlock. */
+export const readOoxmlEncryptionInfo = (path) =>
+  inspectCompoundFile(path, (file) => file.readStream('EncryptionInfo', MAX_ENCRYPTION_INFO_BYTES), null);
+
+/**
+ * [MS-DOC] 2.5.1 FibBase, at the start of the "WordDocument" stream: wIdent 0xA5EC, and fEncrypted (bit 0x0100 of
+ * the flags word at offset 10) set when the document is encrypted or XOR-obfuscated, both opened by a password.
+ */
+export const isEncryptedWordDocument = (path) =>
+  inspectCompoundFile(path, async (file) => {
+    const fib = await file.readStreamHead('WordDocument', 12);
+    return fib.readUInt16LE(0) === 0xa5ec && (fib.readUInt16LE(10) & 0x0100) !== 0;
+  });
+
+/**
+ * [MS-OFFCRYPTO] 2.3.4 (ECMA-376 Document Encryption): an encrypted OOXML document is a CFB container holding the
+ * root-level streams \EncryptionInfo (2.3.4.5) and \EncryptedPackage (2.3.4.4).
+ */
+export const isEncryptedOoxml = (path) =>
+  inspectCompoundFile(path, (file) => file.hasStream('EncryptionInfo') && file.hasStream('EncryptedPackage'));
+
+/**
+ * [MS-PPT] binary presentation: an "EncryptedSummary" stream (2.1.6) exists only in an encrypted document, and an
+ * encrypted file's "Current User" stream (2.1.1), which is never encrypted, holds a CurrentUserAtom (2.3.2:
+ * RecordHeader with recType 0x0FF6, size, headerToken) whose headerToken 0xF3D1C4DF means the file MUST be encrypted.
+ */
+export const isEncryptedBinaryPresentation = (path) =>
+  inspectCompoundFile(path, async (file) => {
+    if (file.hasStream('EncryptedSummary')) return true;
+    const atom = await file.readStreamHead('Current User', 16);
+    return atom.readUInt16LE(2) === 0x0ff6 && atom.readUInt32LE(12) === 0xf3d1c4df;
+  });