@patrickdk77/office-defuse 0.1.0 → 0.1.1

package/dist/objects.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isEquationClass = void 0;
+exports.nestedNotes = nestedNotes;
+exports.compoundRules = compoundRules;
+exports.describeObject = describeObject;
+exports.linkedObject = linkedObject;
+exports.packageData = packageData;
+const cfb_1 = require("./cfb");
+const context_1 = require("./context");
+const oleobj_1 = require("./oleobj");
+const types_1 = require("./types");
+/** The class ids of Equation Editor 3.0 and its kin, which CVE-2017-11882 and CVE-2018-0802 exploit, as oletools lists them. */
+const EQUATION_CLSIDS = new Set(['0002CE02-0000-0000-C000-000000000046', '00021700-0000-0000-C000-000000000046', '0003000B-0000-0000-C000-000000000046', '0004A6B0-0000-0000-C000-000000000046']);
+/** Equation Editor 3.0's ProgID, which rtfobj matches as a prefix. */
+const isEquationClass = (name) => name.trim().toLowerCase().startsWith('equation.3');
+exports.isEquationClass = isEquationClass;
+/** Streams that only an OLE object's storage holds. */
+const OBJECT_STREAMS = new Set(['\x01OLE', '\x01COMPOBJ', '\x01OLE10NATIVE', '\x03OBJINFO']);
+/** Streams that only an ActiveX control's storage holds. */
+const CONTROL_STREAMS = new Set(['\x03OCXNAME', '\x03OCXDATA']);
+/** A CompObj, OLE or ObjInfo stream is small. More is not read. */
+const SMALL = 65536;
+/** Packager's header is short, and its names are at most 1,024 bytes each. */
+const PACKAGE_HEAD = 4096;
+const upper = (e) => e.name.toUpperCase();
+/** Reports what the reader of a compound file inside this one noted, at the place it sits. */
+function nestedNotes(ctx, cfb, location) {
+    for (const n of cfb.notes)
+        ctx.report(types_1.OfficeCategory.Container, n.detail, location, { bytes: n.bytes });
+}
+/** Where a finding about an entry points: `prefix`, then the entry's path. */
+const at = (prefix, e) => [prefix, (0, cfb_1.entryPath)(e)].filter(Boolean).join(' > ');
+/**
+ * The rules every compound file gets: VBA projects, embedded objects and controls, wherever they sit in the tree.
+ * `prefix` names where the file sits when it is inside another, and `rootIsObject` says that its root is itself an
+ * OLE object's storage, as an object in a presentation or an RTF file is.
+ */
+async function compoundRules(ctx, cfb, prefix, rootIsObject) {
+    const projects = new Set();
+    for (const e of cfb.entries) {
+        if (e.kind === 'stream')
+            continue;
+        const child = (name) => e.children.find(c => upper(c) === name);
+        // A VBA project: a VBA storage with a dir stream, which names the modules (MS-OVBA 2.2).
+        const vba = child('VBA');
+        if (vba?.kind === 'storage' && vba.children.some(c => c.kind === 'stream' && upper(c) === 'DIR')) {
+            projects.add(e);
+            ctx.report(types_1.OfficeCategory.Macro, types_1.OfficeDetail.VbaProject, at(prefix, vba), { storage: at(prefix, vba) });
+        }
+        if (e.kind === 'storage' && (upper(e) === '_VBA_PROJECT_CUR' || upper(e) === 'MACROS') && e.children.length && !projects.has(e)) {
+            // Excel's and Word's project storages, without the dir stream a whole project has.
+            ctx.report(types_1.OfficeCategory.Macro, types_1.OfficeDetail.VbaProject, at(prefix, e), { storage: at(prefix, e) });
+        }
+        const names = new Set(e.children.map(upper));
+        const parent = e.parent ? upper(e.parent) : '';
+        const isObject = e.kind === 'root'
+            ? rootIsObject
+            : [...names].some(n => OBJECT_STREAMS.has(n) || CONTROL_STREAMS.has(n)) ||
+                (parent === 'OBJECTPOOL' && e.parent?.parent?.kind === 'root') ||
+                (e.parent?.kind === 'root' && /^MBD[0-9A-F]{8}$/i.test(e.name));
+        if (isObject)
+            await objectRules(ctx, cfb, e, at(prefix, e));
+    }
+}
+/** Reads an OLE object's storage: its class, its CompObj and OLE streams, and Packager's native data. */
+async function describeObject(cfb, e, _location) {
+    const child = (name) => e.children.find(c => c.kind === 'stream' && upper(c) === name);
+    const small = async (name) => {
+        const s = child(name);
+        return s && s.size <= SMALL ? cfb.bytes(s) : undefined;
+    };
+    const clsid = e.clsid === '00000000-0000-0000-0000-000000000000' ? '' : e.clsid;
+    const compObjBytes = await small('\x01COMPOBJ');
+    const comp = compObjBytes ? (0, oleobj_1.parseCompObj)(compObjBytes) : {};
+    const info = { clsid, progId: comp.progId, userType: comp.userType, control: false, linked: false, target: '', url: false, equation: false };
+    info.equation = EQUATION_CLSIDS.has(clsid) || (0, exports.isEquationClass)(comp.progId ?? '');
+    if ([...CONTROL_STREAMS].some(n => child(n))) {
+        const name = await small('\x03OCXNAME');
+        info.control = true;
+        if (name)
+            info.controlName = Buffer.from(name).toString('utf16le').replace(/\0+$/, '');
+        return info;
+    }
+    const oleBytes = await small('\x01OLE');
+    const ole = oleBytes ? (0, oleobj_1.parseOleStream)(oleBytes) : { linked: false, target: '', url: false };
+    Object.assign(info, ole);
+    const native = child('\x01OLE10NATIVE');
+    if (native) {
+        // The stream starts with the native data's size, then Packager's data.
+        info.pkg = (0, oleobj_1.parsePackage)(await cfb.source(native).read(4, PACKAGE_HEAD));
+    }
+    return info;
+}
+/** One OLE object's storage: a control, a linked object, or an embedded one, with what it holds. */
+async function objectRules(ctx, cfb, e, location) {
+    const d = await describeObject(cfb, e, location);
+    const data = { storage: location };
+    if (d.clsid)
+        data.clsid = d.clsid;
+    if (d.progId)
+        data.progId = (0, context_1.clip)(d.progId);
+    if (d.userType)
+        data.className = (0, context_1.clip)(d.userType);
+    if (d.control) {
+        ctx.report(types_1.OfficeCategory.Control, types_1.OfficeDetail.ActiveX, location, d.controlName ? { ...data, name: (0, context_1.clip)(d.controlName) } : data);
+        return;
+    }
+    if (d.pkg) {
+        Object.assign(data, packageData(d.pkg));
+        if (!d.pkg.embedded && d.pkg.sourcePath)
+            ctx.external(types_1.OfficeDetail.Object, d.pkg.sourcePath, location, { storage: location }, 'package link');
+    }
+    if (d.linked)
+        linkedObject(ctx, d, location, { storage: location, ...(d.clsid ? { clsid: d.clsid } : {}) });
+    else
+        ctx.report(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.OleObject, location, data);
+    if (d.equation)
+        ctx.report(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.Equation, location, data);
+}
+/**
+ * Reports a linked object. A URL moniker's target loads from outside the file whatever its text looks like: a
+ * CVE-2017-0199 sample puts a character with a stray high byte where the colon of https: goes.
+ */
+function linkedObject(ctx, d, location, data) {
+    if (d.target && !d.url)
+        ctx.external(types_1.OfficeDetail.Object, d.target, location, data, 'linked object');
+    else
+        ctx.report(types_1.OfficeCategory.External, types_1.OfficeDetail.Object, location, d.target ? { ...data, target: (0, context_1.clip)(d.target, 2000) } : data);
+}
+/** What a finding shows of a Packager object's file: its name and paths, and its size when the object holds it. */
+function packageData(p) {
+    return { fileName: (0, context_1.clip)(p.fileName), sourcePath: (0, context_1.clip)(p.sourcePath, 2000), tempPath: (0, context_1.clip)(p.tempPath, 2000), ...(p.embedded ? { size: p.size } : {}) };
+}

package/dist/odf.d.ts

@@ -1,3 +1,3 @@
-import { type RunContext } from './context';
+import { type ZipContext } from './context';
 /** Inspects an OpenDocument package. */
-export declare function inspectOdf(ctx: RunContext): Promise<void>;
+export declare function inspectOdf(ctx: ZipContext): Promise<void>;

package/dist/offcrypto.d.ts

@@ -0,0 +1,31 @@
+import type { BiffRecord } from './biff';
+import type { CfbEntry, CompoundFile } from './cfb';
+import type { RunContext } from './context';
+import { type ByteSource } from './types';
+import type { Decrypt } from './xls';
+/** The password Excel opens a workbook with when nobody set one to open it (MS-OFFCRYPTO 2.4.3). */
+export declare const DEFAULT_PASSWORD = "VelvetSweatshop";
+/** RC4, which OpenSSL 3 leaves out of its default provider. */
+export declare class Rc4 {
+    private readonly s;
+    private i;
+    private j;
+    constructor(key: Uint8Array);
+    /** XORs the next keystream bytes into a copy of `data`. */
+    crypt(data: Uint8Array): Uint8Array;
+}
+/**
+ * Opens a workbook that its FILEPASS record (MS-XLS 2.4.117) encrypts with RC4 or RC4 CryptoAPI, with the caller's
+ * password or VelvetSweatshop. The records after FILEPASS are encrypted in 1024-byte blocks of the stream, each with its
+ * own key. Their headers are not, but take keystream bytes, and some records are never encrypted.
+ */
+export declare function unlockWorkbook(ctx: RunContext, filePass: BiffRecord, stream: string): Decrypt;
+/**
+ * Inspects an encrypted OOXML package: EncryptionInfo (MS-OFFCRYPTO 2.3.4) names the cipher, and the caller's password
+ * or VelvetSweatshop gives the key. The package it decrypts goes through the OOXML rules, read in place: Agile
+ * encryption works in 4,096-byte segments and Standard in 16-byte blocks, so nothing is decrypted that is not read.
+ */
+export declare function openPackage(ctx: RunContext, cfb: CompoundFile, info: CfbEntry, pkg: CfbEntry): Promise<{
+    source: ByteSource;
+    size: number;
+}>;

package/dist/offcrypto.js

@@ -0,0 +1,408 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Rc4 = exports.DEFAULT_PASSWORD = void 0;
+exports.unlockWorkbook = unlockWorkbook;
+exports.openPackage = openPackage;
+const crypto = __importStar(require("node:crypto"));
+const errors_1 = require("./errors");
+const oleobj_1 = require("./oleobj");
+const types_1 = require("./types");
+/** The password Excel opens a workbook with when nobody set one to open it (MS-OFFCRYPTO 2.4.3). */
+exports.DEFAULT_PASSWORD = 'VelvetSweatshop';
+/** MS-OFFCRYPTO allows a spin count of at most 10,000,000. */
+const MAX_SPIN = 10_000_000;
+/** More of a Standard EncryptionInfo than its header and verifier take, which are a few hundred bytes. */
+const STANDARD_INFO = 4096;
+/** A source's bytes from `from` to `to`, in pieces. */
+async function* chunks(source, from, to) {
+    for (let at = from; at < to; at += 65536)
+        yield source.read(at, Math.min(65536, to - at));
+}
+const required = (reason, data = {}) => new errors_1.StopError(types_1.OfficeCategory.Encrypted, types_1.OfficeDetail.PasswordRequired, `No password at hand opens the file: ${reason}`, { ...data, reason });
+/** A file encrypted with an algorithm this reader does not decrypt. It never reaches OpenSSL. */
+const unsupported = (algorithm, data = {}) => new errors_1.StopError(types_1.OfficeCategory.Encrypted, types_1.OfficeDetail.UnsupportedAlgorithm, `The file is encrypted with ${algorithm}, which this reader does not decrypt`, { ...data, algorithm });
+const HASHES = new Map([
+    ['SHA1', 'sha1'],
+    ['SHA256', 'sha256'],
+    ['SHA384', 'sha384'],
+    ['SHA512', 'sha512'],
+]);
+const AES = new Map([
+    [128, { cbc: 'aes-128-cbc', ecb: 'aes-128-ecb', detail: types_1.OfficeDetail.Aes128, bits: 128 }],
+    [192, { cbc: 'aes-192-cbc', ecb: 'aes-192-ecb', detail: types_1.OfficeDetail.Aes192, bits: 192 }],
+    [256, { cbc: 'aes-256-cbc', ecb: 'aes-256-ecb', detail: types_1.OfficeDetail.Aes256, bits: 256 }],
+]);
+/** CALG_AES_128, CALG_AES_192 and CALG_AES_256, by key size. */
+const STANDARD_AES = new Map([
+    [128, 0x660e],
+    [192, 0x660f],
+    [256, 0x6610],
+]);
+/** A value from the file for a message, cut short. */
+const shown = (v) => (v ?? 'none').slice(0, 40);
+/** The passwords tried, in order: the caller's, then Excel's default. */
+function passwords(ctx) {
+    const out = ctx.settings.password !== undefined ? [{ password: ctx.settings.password, supplied: true }] : [];
+    return [...out, { password: exports.DEFAULT_PASSWORD, supplied: false }];
+}
+/** Which password opened the file, and the cipher, as findings. */
+function opened(ctx, supplied, cipher, location, bits) {
+    ctx.report(types_1.OfficeCategory.Encrypted, supplied ? types_1.OfficeDetail.UserPassword : types_1.OfficeDetail.DefaultPassword, location, supplied ? {} : { password: exports.DEFAULT_PASSWORD });
+    ctx.report(types_1.OfficeCategory.Encrypted, cipher, location, { bits });
+}
+const utf16le = (s) => Buffer.from(s, 'utf16le');
+const le32 = (n) => {
+    const b = Buffer.alloc(4);
+    b.writeUInt32LE(n >>> 0);
+    return b;
+};
+const hash = (algorithm, ...parts) => {
+    const h = crypto.createHash(algorithm);
+    for (const p of parts)
+        h.update(p);
+    return h.digest();
+};
+/** RC4, which OpenSSL 3 leaves out of its default provider. */
+class Rc4 {
+    s = new Uint8Array(256);
+    i = 0;
+    j = 0;
+    constructor(key) {
+        for (let k = 0; k < 256; k++)
+            this.s[k] = k;
+        for (let k = 0, j = 0; k < 256; k++) {
+            j = (j + this.s[k] + key[k % key.length]) & 255;
+            [this.s[k], this.s[j]] = [this.s[j], this.s[k]];
+        }
+    }
+    /** XORs the next keystream bytes into a copy of `data`. */
+    crypt(data) {
+        const out = new Uint8Array(data.length);
+        for (let k = 0; k < data.length; k++) {
+            this.i = (this.i + 1) & 255;
+            this.j = (this.j + this.s[this.i]) & 255;
+            [this.s[this.i], this.s[this.j]] = [this.s[this.j], this.s[this.i]];
+            out[k] = data[k] ^ this.s[(this.s[this.i] + this.s[this.j]) & 255];
+        }
+        return out;
+    }
+}
+exports.Rc4 = Rc4;
+/** Office binary document RC4 (MS-OFFCRYPTO 2.3.6): MD5, a 40-bit truncation and the salt. */
+function rc4Key(password, salt) {
+    const h0 = hash('md5', utf16le(password)).subarray(0, 5);
+    const buffer = Buffer.concat(Array.from({ length: 16 }, () => Buffer.concat([h0, salt])));
+    const h1 = hash('md5', buffer).subarray(0, 5);
+    return block => hash('md5', h1, le32(block));
+}
+/** RC4 CryptoAPI (MS-OFFCRYPTO 2.3.5.2): SHA-1 of the salt and password, then of the block number. A 40-bit key is padded to 128 bits. */
+function cryptoApiKey(password, salt, bits) {
+    const h0 = hash('sha1', salt, utf16le(password));
+    return block => {
+        const h = hash('sha1', h0, le32(block));
+        return bits === 40 ? Buffer.concat([h.subarray(0, 5), Buffer.alloc(11)]) : h.subarray(0, bits / 8);
+    };
+}
+/**
+ * Opens a workbook that its FILEPASS record (MS-XLS 2.4.117) encrypts with RC4 or RC4 CryptoAPI, with the caller's
+ * password or VelvetSweatshop. The records after FILEPASS are encrypted in 1024-byte blocks of the stream, each with its
+ * own key. Their headers are not, but take keystream bytes, and some records are never encrypted.
+ */
+function unlockWorkbook(ctx, filePass, stream) {
+    const r = new oleobj_1.ByteReader(filePass.body);
+    let key;
+    let cipher = types_1.OfficeDetail.Rc4_40;
+    let bits = 40;
+    try {
+        const type = r.u16();
+        if (type !== 1)
+            throw unsupported('XOR obfuscation', { stream });
+        const major = r.u16();
+        const minor = r.u16();
+        if (major === 1 && minor === 1) {
+            const salt = r.bytes(16);
+            const verifier = r.bytes(16);
+            const verifierHash = r.bytes(16);
+            for (const p of passwords(ctx)) {
+                const k = rc4Key(p.password, salt);
+                const plain = new Rc4(k(0)).crypt(Buffer.concat([verifier, verifierHash]));
+                if (hash('md5', plain.subarray(0, 16)).equals(Buffer.from(plain.subarray(16, 32)))) {
+                    key = k;
+                    opened(ctx, p.supplied, types_1.OfficeDetail.Rc4_40, stream, 40);
+                    break;
+                }
+            }
+        }
+        else if ((major === 2 || major === 3 || major === 4) && minor === 2) {
+            r.skip(4);
+            const headerSize = r.u32();
+            const header = new oleobj_1.ByteReader(r.bytes(headerSize));
+            header.skip(8);
+            const algorithm = header.u32();
+            header.skip(4);
+            bits = header.u32() || 40;
+            if (algorithm !== 0x6801 || bits < 40 || bits > 128 || bits % 8)
+                throw unsupported(`CryptoAPI algorithm 0x${algorithm.toString(16)} with a ${bits}-bit key`, { stream });
+            cipher = bits === 40 ? types_1.OfficeDetail.Rc4_40 : bits === 128 ? types_1.OfficeDetail.Rc4_128 : types_1.OfficeDetail.Rc4Other;
+            const saltSize = r.u32();
+            const salt = r.bytes(saltSize);
+            const verifier = r.bytes(16);
+            const hashSize = r.u32();
+            const verifierHash = r.bytes(Math.min(hashSize, r.left));
+            for (const p of passwords(ctx)) {
+                const k = cryptoApiKey(p.password, salt, bits);
+                const plain = new Rc4(k(0)).crypt(Buffer.concat([verifier, verifierHash]));
+                if (hash('sha1', plain.subarray(0, 16)).equals(Buffer.from(plain.subarray(16, 36)))) {
+                    key = k;
+                    opened(ctx, p.supplied, cipher, stream, bits);
+                    break;
+                }
+            }
+        }
+        else
+            throw unsupported(`encryption version ${major}.${minor}`, { stream });
+    }
+    catch (e) {
+        if (e instanceof oleobj_1.Truncated)
+            throw required('a FILEPASS record cut short', { stream });
+        throw e;
+    }
+    if (!key)
+        throw required('the workbook is encrypted with a password that is not VelvetSweatshop', { stream });
+    return biffDecrypt(key);
+}
+/** Records MS-XLS 2.2.10 never encrypts: BOF, FILEPASS, UsrExcl, FileLock, InterfaceHdr, RRDInfo and RRDHead. */
+const PLAIN = new Set([0x0809, 0x002f, 0x0194, 0x0195, 0x00e1, 0x0196, 0x0138]);
+/** Only the records after FILEPASS reach the function it returns. */
+function biffDecrypt(key) {
+    let block = -1;
+    let stream = new Uint8Array(0);
+    const keystream = (b) => {
+        if (b !== block) {
+            block = b;
+            stream = new Rc4(key(b)).crypt(new Uint8Array(1024));
+        }
+        return stream;
+    };
+    return r => {
+        if (PLAIN.has(r.type))
+            return r.body;
+        const out = new Uint8Array(r.body);
+        // BoundSheet8's lbPlyPos stays plain, so a reader can find each sheet without the key.
+        const from = r.type === 0x0085 ? 4 : 0;
+        for (let k = from; k < out.length; k++) {
+            const at = r.offset + 4 + k;
+            out[k] ^= keystream(Math.floor(at / 1024))[at % 1024];
+        }
+        return out;
+    };
+}
+/**
+ * Inspects an encrypted OOXML package: EncryptionInfo (MS-OFFCRYPTO 2.3.4) names the cipher, and the caller's password
+ * or VelvetSweatshop gives the key. The package it decrypts goes through the OOXML rules, read in place: Agile
+ * encryption works in 4,096-byte segments and Standard in 16-byte blocks, so nothing is decrypted that is not read.
+ */
+async function openPackage(ctx, cfb, info, pkg) {
+    const source = cfb.source(info);
+    const version = await source.read(0, 8);
+    const major = version.length >= 4 ? version[0] | (version[1] << 8) : 0;
+    const minor = version.length >= 4 ? version[2] | (version[3] << 8) : 0;
+    let cipher;
+    // Agile's XML goes to the tokenizer in pieces. Standard's binary header is a few hundred bytes.
+    if (major === 4 && minor === 4)
+        cipher = await agile(ctx, chunks(source, 8, info.size));
+    else if ((major === 3 || major === 4) && minor === 2)
+        cipher = standard(await source.read(8, STANDARD_INFO));
+    else
+        throw unsupported(`encryption version ${major}.${minor}`, { stream: info.name });
+    const head = await cfb.source(pkg).read(0, 8);
+    if (head.length < 8)
+        throw required('an EncryptedPackage stream cut short', { stream: pkg.name });
+    const size = Number(Buffer.from(head).readBigUInt64LE(0));
+    if (size > pkg.size - 8)
+        throw required('an EncryptedPackage stream shorter than the size it gives', { stream: pkg.name });
+    for (const p of passwords(ctx)) {
+        (0, errors_1.checkTime)(ctx.settings.deadline);
+        const key = cipher.key(p.password);
+        if (!key)
+            continue;
+        opened(ctx, p.supplied, cipher.cipher.detail, pkg.name, cipher.cipher.bits);
+        const data = cfb.source(pkg);
+        return { source: cipher.source((offset, length) => data.read(8 + offset, length), size, key), size };
+    }
+    throw required('the package is encrypted with a password that is not VelvetSweatshop', { stream: pkg.name });
+}
+/** AES without padding over whole blocks: ECB, or CBC from `iv`. */
+function aes(cipher, key, data, iv) {
+    const d = crypto.createDecipheriv(iv ? cipher.cbc : cipher.ecb, key, iv ?? null);
+    d.setAutoPadding(false);
+    const whole = data.subarray(0, data.length - (data.length % 16));
+    return Buffer.concat([d.update(whole), d.final()]);
+}
+/** Standard encryption (MS-OFFCRYPTO 2.3.4.5): AES-ECB with a key from SHA-1 over 50,000 rounds. */
+function standard(b) {
+    const r = new oleobj_1.ByteReader(b);
+    try {
+        const headerSize = r.u32();
+        const header = new oleobj_1.ByteReader(r.bytes(headerSize));
+        header.skip(8);
+        const algorithm = header.u32();
+        const hashAlgorithm = header.u32();
+        const bits = header.u32();
+        // CALG_AES_128, _192 and _256, which name their key size, with SHA-1.
+        const cipher = AES.get(bits);
+        if (!cipher || algorithm !== STANDARD_AES.get(bits) || (hashAlgorithm !== 0x8004 && hashAlgorithm !== 0))
+            throw unsupported(`Standard encryption with algorithm 0x${algorithm.toString(16)}, hash 0x${hashAlgorithm.toString(16)} and a ${bits}-bit key`);
+        r.skip(4);
+        const salt = r.bytes(16);
+        const verifier = r.bytes(16);
+        r.skip(4);
+        const verifierHash = r.bytes(32);
+        const keyOf = (password) => {
+            let h = hash('sha1', salt, utf16le(password));
+            for (let i = 0; i < 50000; i++)
+                h = hash('sha1', le32(i), h);
+            const final = hash('sha1', h, le32(0));
+            const x = (fill) => {
+                const buf = Buffer.alloc(64, fill);
+                for (let i = 0; i < final.length; i++)
+                    buf[i] ^= final[i];
+                return hash('sha1', buf);
+            };
+            return Buffer.concat([x(0x36), x(0x5c)]).subarray(0, bits / 8);
+        };
+        return {
+            cipher,
+            key(password) {
+                const key = keyOf(password);
+                const v = aes(cipher, key, verifier);
+                const vh = aes(cipher, key, verifierHash);
+                return hash('sha1', v).equals(Buffer.from(vh.subarray(0, 20))) ? key : undefined;
+            },
+            source: (read, size, key) => blockSource(size, 16, async (index, count) => aes(cipher, key, await read(index * 16, count * 16))),
+        };
+    }
+    catch (e) {
+        if (e instanceof oleobj_1.Truncated)
+            throw required('a Standard EncryptionInfo cut short');
+        throw e;
+    }
+}
+/** Agile encryption (MS-OFFCRYPTO 2.3.4.10): an XML descriptor, a password key encryptor, and AES-CBC in 4,096-byte segments. */
+async function agile(ctx, xml) {
+    const found = {};
+    const ENCRYPTION = 'http://schemas.microsoft.com/office/2006/encryption';
+    const PASSWORD = 'http://schemas.microsoft.com/office/2006/keyEncryptor/password';
+    await ctx.parseXml('EncryptionInfo', xml, {
+        start(el) {
+            const all = Object.fromEntries(el.attributes.filter(a => a.ns === '').map(a => [a.local, a.value]));
+            if (el.ns === ENCRYPTION && el.local === 'keyData')
+                found.keyData ??= all;
+            else if (el.ns === PASSWORD && el.local === 'encryptedKey')
+                found.encryptedKey ??= all;
+        },
+    });
+    const kd = found.keyData;
+    const ek = found.encryptedKey;
+    if (!kd || !ek)
+        throw required('an Agile descriptor without key data or a password key');
+    /** The hash and cipher a key data or key encryptor element names, when both are on the allowlist. */
+    const algorithms = (a) => {
+        const h = HASHES.get(a.hashAlgorithm);
+        const c = AES.get(Number(a.keyBits));
+        if (!h || !c || a.cipherAlgorithm !== 'AES' || a.cipherChaining !== 'ChainingModeCBC' || Number(a.blockSize) !== 16)
+            throw unsupported(`Agile encryption with ${shown(a.cipherAlgorithm)} in ${shown(a.cipherChaining)}, a ${shown(a.keyBits)}-bit key and ${shown(a.hashAlgorithm)}`);
+        return { h, c };
+    };
+    const { h: dh, c: dc } = algorithms(kd);
+    const { h: eh, c: ec } = algorithms(ek);
+    const spin = Number(ek.spinCount);
+    if (!Number.isInteger(spin) || spin < 0 || spin > MAX_SPIN)
+        throw required('an Agile spin count past 10,000,000');
+    const b64 = (s) => Buffer.from(s ?? '', 'base64');
+    const pad = (b, n, fill) => (b.length >= n ? b.subarray(0, n) : Buffer.concat([b, Buffer.alloc(n - b.length, fill)]));
+    const salt = b64(ek.saltValue);
+    const BLOCKS = { input: Buffer.from('fea7d2763b4b9e79', 'hex'), value: Buffer.from('d7aa0f6d3061344e', 'hex'), key: Buffer.from('146e0be7abacd0d6', 'hex') };
+    const dsalt = b64(kd.saltValue);
+    return {
+        cipher: dc,
+        key(password) {
+            let h = hash(eh, salt, utf16le(password));
+            for (let i = 0; i < spin; i++) {
+                if (i % 65536 === 0)
+                    (0, errors_1.checkTime)(ctx.settings.deadline);
+                h = hash(eh, le32(i), h);
+            }
+            const derive = (block) => pad(hash(eh, h, block), ec.bits / 8, 0x36);
+            const iv = pad(salt, 16, 0x36);
+            const input = aes(ec, derive(BLOCKS.input), b64(ek.encryptedVerifierHashInput), iv).subarray(0, Number(ek.saltSize) || 16);
+            const expected = aes(ec, derive(BLOCKS.value), b64(ek.encryptedVerifierHashValue), iv);
+            const got = hash(eh, input);
+            if (!got.equals(Buffer.from(expected.subarray(0, got.length))))
+                return undefined;
+            return aes(ec, derive(BLOCKS.key), b64(ek.encryptedKeyValue), iv).subarray(0, dc.bits / 8);
+        },
+        source: (read, size, key) => blockSource(size, 4096, async (index, count) => {
+            const raw = await read(index * 4096, count * 4096);
+            const out = [];
+            for (let k = 0; k * 4096 < raw.length; k++)
+                out.push(aes(dc, key, raw.subarray(k * 4096, (k + 1) * 4096), pad(hash(dh, dsalt, le32(index + k)), 16, 0x36)));
+            return Buffer.concat(out);
+        }),
+    };
+}
+/** A source over decrypted data, decrypting the whole blocks each read covers, and keeping the last ones decrypted. */
+function blockSource(size, unit, decrypt) {
+    let cached;
+    return {
+        size: async () => size,
+        async read(offset, length) {
+            const end = Math.min(size, offset + length);
+            const first = Math.floor(offset / unit);
+            const last = Math.floor((end - 1) / unit);
+            let bytes;
+            if (cached && cached.index <= first && cached.index + cached.bytes.length / unit > last)
+                bytes = cached.bytes.subarray((first - cached.index) * unit);
+            else {
+                // A small read decrypts 64 KiB from where it starts, since the ZIP reader reads on from there.
+                const count = Math.max(last - first + 1, Math.ceil(65536 / unit));
+                bytes = await decrypt(first, count);
+                cached = { index: first, bytes };
+            }
+            return bytes.subarray(offset - first * unit, end - first * unit);
+        },
+    };
+}

package/dist/ole.d.ts

@@ -0,0 +1,12 @@
+import type { CompoundFile } from './cfb';
+import type { RunContext } from './context';
+/** The families a compound file can hold, by the stream or storage that marks each. */
+type Family = 'word' | 'excel' | 'powerpoint' | 'visio' | 'outlook' | 'publisher' | 'project' | 'encrypted';
+/** What the root of a compound file holds, read by the names of its children, ignoring case as MS-CFB does. */
+export declare function families(cfb: CompoundFile): Family[];
+/**
+ * Inspects a compound file: the rules every compound file gets, over its whole tree, and then those of the format
+ * its root names.
+ */
+export declare function inspectCompound(ctx: RunContext, cfb: CompoundFile): Promise<void>;
+export {};