@patrickdk77/office-defuse 0.1.0 → 0.2.0

package/dist/biff.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecordReader = exports.R = void 0;
+exports.xlString = xlString;
+exports.parseBoundSheet = parseBoundSheet;
+exports.parseLbl = parseLbl;
+exports.autoName = autoName;
+const errors_1 = require("./errors");
+const io_1 = require("./io");
+const oleobj_1 = require("./oleobj");
+/** Record types this reader acts on (MS-XLS 2.3). */
+exports.R = {
+    bof: 0x0809,
+    eof: 0x000a,
+    filePass: 0x002f,
+    continue: 0x003c,
+    lbl: 0x0018,
+    externName: 0x0023,
+    boundSheet: 0x0085,
+    template: 0x0060,
+    addIn: 0x0087,
+    supBook: 0x01ae,
+    externSheet: 0x0017,
+    obj: 0x005d,
+    hlink: 0x01b8,
+};
+/**
+ * Reads the records of a workbook stream one at a time, from `start` to the end of the stream. A record's body may
+ * run past the stream's end only by being cut short, which stops the reading as Excel stops.
+ */
+class RecordReader {
+    stream;
+    deadline;
+    reader;
+    pos;
+    constructor(cfb, stream, start, deadline) {
+        this.stream = stream;
+        this.deadline = deadline;
+        this.reader = new io_1.Reader(cfb.source(stream), stream.size, 16384, 8);
+        this.pos = start;
+    }
+    async next() {
+        if (this.pos + 4 > this.stream.size)
+            return undefined;
+        const h = await this.reader.read(this.pos, 4);
+        const type = h[0] | (h[1] << 8);
+        const length = h[2] | (h[3] << 8);
+        if (this.pos + 4 + length > this.stream.size)
+            return undefined;
+        const offset = this.pos;
+        const body = await this.reader.read(this.pos + 4, length);
+        this.pos += 4 + length;
+        if ((offset & 0xffff) < 4)
+            (0, errors_1.checkTime)(this.deadline);
+        return { type, offset, body };
+    }
+}
+exports.RecordReader = RecordReader;
+/** BIFF8 writes strings with a flag byte: 8-bit characters, or 16-bit ones when its low bit is set. */
+function xlString(b, at, chars) {
+    if (at >= b.length)
+        return { text: '', next: at };
+    const wide = (b[at] & 1) === 1;
+    const start = at + 1;
+    const end = Math.min(b.length, start + chars * (wide ? 2 : 1));
+    return { text: wide ? (0, oleobj_1.utf16)(b.subarray(start, end)) : (0, oleobj_1.latin1)(b.subarray(start, end)), next: end };
+}
+/** A BoundSheet record, in BIFF8 or BIFF5. */
+function parseBoundSheet(body, biff8) {
+    const position = (body[0] | (body[1] << 8) | (body[2] << 16) | (body[3] << 24)) >>> 0;
+    const state = body[4] & 3;
+    const type = body[5];
+    const cch = body[6] ?? 0;
+    const name = biff8 ? xlString(body, 7, cch).text : (0, oleobj_1.latin1)(body.subarray(7, 7 + cch));
+    return { position, state, type, name };
+}
+/** Built-in names Excel runs as macros (MS-XLS 2.5.112): Auto_Open and Auto_Activate as the workbook opens, Auto_Close and Auto_Deactivate as it closes. */
+const BUILTIN_NAMES = { 1: 'Auto_Open', 2: 'Auto_Close', 10: 'Auto_Activate', 11: 'Auto_Deactivate' };
+/** A defined name, in BIFF8 or BIFF5, with a built-in name spelled out. */
+function parseLbl(body, biff8) {
+    const flags = body[0] | (body[1] << 8);
+    const cch = body[3] ?? 0;
+    const builtin = (flags & 0x20) !== 0;
+    const name = biff8 ? xlString(body, 14, cch).text : (0, oleobj_1.latin1)(body.subarray(14, 14 + cch));
+    const shown = builtin && name.length > 0 ? (BUILTIN_NAMES[name.charCodeAt(0)] ?? `built-in name ${name.charCodeAt(0)}`) : name;
+    return { name: shown, builtin, hidden: (flags & 1) !== 0 };
+}
+/** The event a defined name runs a macro on, when Excel runs it on one: any name that starts with Auto_Open and so on. */
+function autoName(name) {
+    const m = /^(?:_xlnm\.)?(auto_open|auto_close|auto_activate|auto_deactivate)/i.exec(name);
+    if (!m)
+        return undefined;
+    const event = m[1].toLowerCase();
+    return { event: `${event[0].toUpperCase()}${event.slice(1, 5)}${event[5].toUpperCase()}${event.slice(6)}`, onOpen: event === 'auto_open' || event === 'auto_activate' };
+}

package/dist/cfb-writer.d.ts

@@ -0,0 +1,25 @@
+import type { ByteSink, ByteSource } from './types';
+/** A stream or storage to write. A storage's children may come in any order; the writer sorts them. */
+export type CfbNode = {
+    kind: 'storage';
+    name: string;
+    clsid: string;
+    children: CfbNode[];
+} | {
+    kind: 'stream';
+    name: string;
+    size: number;
+    source: ByteSource;
+};
+/** The root of the file to write: its class id and what it holds. */
+export interface CfbTree {
+    clsid: string;
+    children: CfbNode[];
+}
+/**
+ * Writes a compound file (MS-CFB, version 3 with 512-byte sectors) to an append-only sink. The children of each
+ * storage go into a balanced tree in MS-CFB's name order, colored as a valid red-black tree. Streams under 4,096 bytes
+ * go into the mini stream. The writer holds the allocation tables and the directory, and reads each stream once, in
+ * order, from its source.
+ */
+export declare function writeCfb(tree: CfbTree, sink: ByteSink, deadline?: number): Promise<void>;

package/dist/cfb-writer.js

@@ -0,0 +1,314 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeCfb = writeCfb;
+const errors_1 = require("./errors");
+const MINI_SECTOR = 64;
+const MINI_CUTOFF = 4096;
+const FREE = 0xffffffff;
+const END_OF_CHAIN = 0xfffffffe;
+const FAT_SECTOR = 0xfffffffd;
+const DIFAT_SECTOR = 0xfffffffc;
+const NO_STREAM = 0xffffffff;
+const HEADER_FAT = 109;
+/** A GUID as Windows shows it, back to its 16 bytes. '' gives zeros. */
+function guidBytes(clsid) {
+    const out = new Uint8Array(16);
+    const h = clsid.replace(/-/g, '');
+    if (h.length !== 32)
+        return out;
+    const byte = (i) => Number.parseInt(h.slice(i * 2, i * 2 + 2), 16);
+    const order = [3, 2, 1, 0, 5, 4, 7, 6, 8, 9, 10, 11, 12, 13, 14, 15];
+    for (const [i, from] of order.entries())
+        out[i] = byte(from);
+    return out;
+}
+/** MS-CFB's order of names in a storage: the shorter first, then by their upper-case code units. */
+function compareNames(a, b) {
+    if (a.length !== b.length)
+        return a.length - b.length;
+    const ua = a.toUpperCase();
+    const ub = b.toUpperCase();
+    return ua < ub ? -1 : ua > ub ? 1 : 0;
+}
+class Bytes {
+    b;
+    constructor(n) {
+        this.b = Buffer.alloc(n);
+    }
+    u16(at, v) {
+        this.b.writeUInt16LE(v, at);
+    }
+    u32(at, v) {
+        this.b.writeUInt32LE(v >>> 0, at);
+    }
+}
+/**
+ * Writes a compound file (MS-CFB, version 3 with 512-byte sectors) to an append-only sink. The children of each
+ * storage go into a balanced tree in MS-CFB's name order, colored as a valid red-black tree. Streams under 4,096 bytes
+ * go into the mini stream. The writer holds the allocation tables and the directory, and reads each stream once, in
+ * order, from its source.
+ */
+async function writeCfb(tree, sink, deadline) {
+    const ss = 512;
+    const per = ss / 4;
+    // The directory: the root, then every storage's children, depth first.
+    const entries = [{ name: 'Root Entry', type: 5, clsid: guidBytes(tree.clsid), left: NO_STREAM, right: NO_STREAM, child: NO_STREAM, red: false, start: END_OF_CHAIN, size: 0 }];
+    const place = (children) => {
+        const sorted = [...children].sort((a, b) => compareNames(a.name, b.name));
+        const ids = [];
+        for (const c of sorted) {
+            ids.push(entries.length);
+            entries.push({
+                name: c.name,
+                type: c.kind === 'storage' ? 1 : 2,
+                clsid: c.kind === 'storage' ? guidBytes(c.clsid) : new Uint8Array(16),
+                left: NO_STREAM,
+                right: NO_STREAM,
+                child: NO_STREAM,
+                red: false,
+                start: END_OF_CHAIN,
+                size: c.kind === 'stream' ? c.size : 0,
+                node: c,
+            });
+        }
+        // A median split puts every leaf on the last two levels. The deepest level is red and the rest black, so every
+        // path from the root down passes the same number of black entries.
+        const height = Math.ceil(Math.log2(sorted.length + 1));
+        const build = (lo, hi, depth) => {
+            if (lo > hi)
+                return NO_STREAM;
+            const mid = (lo + hi) >>> 1;
+            const e = entries[ids[mid]];
+            e.left = build(lo, mid - 1, depth + 1);
+            e.right = build(mid + 1, hi, depth + 1);
+            e.red = depth === height - 1 && height > 1;
+            return ids[mid];
+        };
+        const root = build(0, sorted.length - 1, 0);
+        for (const [i, c] of sorted.entries())
+            if (c.kind === 'storage')
+                entries[ids[i]].child = place(c.children);
+        return root;
+    };
+    entries[0].child = place(tree.children);
+    // Sectors: the FAT and the DIFAT, then the mini stream, the large streams, the directory and the mini FAT, then any
+    // free sectors the tail needs. The first sector after the header is always a FAT sector, whose sector numbers can
+    // never spell a signature, so no stream lands where PDF readers look for a header.
+    // Version 3 keeps sizes in 32 bits.
+    if (entries.some(e => e.size > 0xffffffff))
+        throw new Error('A stream is too large for a version 3 compound file');
+    const small = entries.filter(e => e.type === 2 && e.size > 0 && e.size < MINI_CUTOFF);
+    const large = entries.filter(e => e.type === 2 && e.size >= MINI_CUTOFF);
+    let miniSectors = 0;
+    const miniStart = new Map();
+    for (const e of small) {
+        miniStart.set(e, miniSectors);
+        miniSectors += Math.ceil(e.size / MINI_SECTOR);
+    }
+    const miniStreamSize = miniSectors * MINI_SECTOR;
+    const miniStreamSectors = Math.ceil(miniStreamSize / ss);
+    const largeSectors = large.reduce((t, e) => t + Math.ceil(e.size / ss), 0);
+    const dirSectors = Math.ceil(entries.length / (ss / 128));
+    const miniFatSectors = Math.ceil(miniSectors / per);
+    const content = miniStreamSectors + largeSectors + dirSectors + miniFatSectors;
+    /** Where everything goes with `pad` free sectors at the end. */
+    const layout = (pad) => {
+        // The FAT must describe its own sectors and the DIFAT's, so their counts grow together until they fit.
+        let fatSectors = 0;
+        let difatSectors = 0;
+        for (;;) {
+            const total = content + pad + fatSectors + difatSectors;
+            const needFat = Math.ceil(total / per);
+            const needDifat = needFat > HEADER_FAT ? Math.ceil((needFat - HEADER_FAT) / (per - 1)) : 0;
+            if (needFat === fatSectors && needDifat === difatSectors)
+                break;
+            fatSectors = needFat;
+            difatSectors = needDifat;
+        }
+        const base = fatSectors + difatSectors;
+        let next = base + miniStreamSectors;
+        const starts = new Map();
+        for (const e of large) {
+            starts.set(e, next);
+            next += Math.ceil(e.size / ss);
+        }
+        const dirStart = next;
+        const miniFatStart = miniSectors ? dirStart + dirSectors : END_OF_CHAIN;
+        const sectors = base + content + pad;
+        return { fatSectors, difatSectors, base, starts, dirStart, miniFatStart, pad, sectors, size: (sectors + 1) * ss };
+    };
+    const apply = (l) => {
+        for (const e of small)
+            e.start = miniStart.get(e) ?? 0;
+        for (const e of large)
+            e.start = l.starts.get(e) ?? 0;
+        entries[0].start = miniStreamSectors ? l.base : END_OF_CHAIN;
+        entries[0].size = miniStreamSize;
+    };
+    const fatOf = (l) => {
+        const fat = new Uint32Array(l.fatSectors * per).fill(FREE);
+        const chain = (start, count) => {
+            for (let i = 0; i < count; i++)
+                fat[start + i] = i === count - 1 ? END_OF_CHAIN : start + i + 1;
+        };
+        for (let i = 0; i < l.fatSectors; i++)
+            fat[i] = FAT_SECTOR;
+        for (let i = 0; i < l.difatSectors; i++)
+            fat[l.fatSectors + i] = DIFAT_SECTOR;
+        if (miniStreamSectors)
+            chain(l.base, miniStreamSectors);
+        for (const e of large)
+            chain(e.start, Math.ceil(e.size / ss));
+        chain(l.dirStart, dirSectors);
+        if (miniFatSectors)
+            chain(l.miniFatStart, miniFatSectors);
+        return fat;
+    };
+    const directoryOf = () => {
+        const dir = new Bytes(dirSectors * ss);
+        for (let id = 0; id < dirSectors * (ss / 128); id++) {
+            const at = id * 128;
+            const e = entries[id];
+            if (!e) {
+                dir.u32(at + 0x44, NO_STREAM);
+                dir.u32(at + 0x48, NO_STREAM);
+                dir.u32(at + 0x4c, NO_STREAM);
+                continue;
+            }
+            const name = Buffer.from(e.name, 'utf16le').subarray(0, 62);
+            name.copy(dir.b, at);
+            dir.u16(at + 0x40, name.length + 2);
+            dir.b[at + 0x42] = e.type;
+            dir.b[at + 0x43] = e.red ? 0 : 1;
+            dir.u32(at + 0x44, e.left);
+            dir.u32(at + 0x48, e.right);
+            dir.u32(at + 0x4c, e.child);
+            Buffer.from(e.clsid).copy(dir.b, at + 0x50);
+            dir.u32(at + 0x74, e.type === 1 ? 0 : e.size === 0 && e.type === 2 ? END_OF_CHAIN : e.start);
+            dir.u32(at + 0x78, e.size);
+        }
+        return dir.b;
+    };
+    const miniFat = new Uint32Array(miniFatSectors * per).fill(FREE);
+    for (const e of small) {
+        const first = miniStart.get(e) ?? 0;
+        const n = Math.ceil(e.size / MINI_SECTOR);
+        for (let i = 0; i < n; i++)
+            miniFat[first + i] = i === n - 1 ? END_OF_CHAIN : first + i + 1;
+    }
+    /**
+     * The bytes the file holds in [from, to), with streams read from their sources. The header and the DIFAT read as
+     * zeros, since what the header holds is fixed and the DIFAT holds only sector numbers.
+     */
+    const bytesAt = async (l, from, to) => {
+        const out = Buffer.alloc(Math.max(0, to - from));
+        const put = (at, b) => {
+            const s = Math.max(at, from);
+            const e = Math.min(at + b.length, to);
+            if (e > s)
+                out.set(b.subarray(s - at, e - at), s - from);
+        };
+        const putStream = async (at, e) => {
+            const node = e.node;
+            const s = Math.max(at, from);
+            const end = Math.min(at + e.size, to);
+            if (end <= s || node?.kind !== 'stream')
+                return;
+            put(s, await node.source.read(s - at, end - s));
+        };
+        const fat = fatOf(l);
+        put(ss, Buffer.from(fat.buffer));
+        for (const e of small)
+            await putStream((l.base + 1) * ss + (miniStart.get(e) ?? 0) * MINI_SECTOR, e);
+        for (const e of large)
+            await putStream((e.start + 1) * ss, e);
+        put((l.dirStart + 1) * ss, directoryOf());
+        if (miniFatSectors)
+            put((l.miniFatStart + 1) * ss, Buffer.from(miniFat.buffer));
+        return out;
+    };
+    // ZIP readers look for an end record in the last 65,557 bytes. A stream that ends with one, such as an embedded
+    // package, would make the file open as that archive too, so free sectors of zeros push it out of their reach.
+    const ZIP_WINDOW = 22 + 0xffff;
+    const END_RECORD = Buffer.from([0x50, 0x4b, 0x05, 0x06]);
+    const lastEndRecord = async (l) => {
+        const from = Math.max(ss, l.size - ZIP_WINDOW);
+        const found = (await bytesAt(l, from, l.size)).lastIndexOf(END_RECORD);
+        return found < 0 ? -1 : from + found;
+    };
+    let plan = layout(0);
+    apply(plan);
+    const endAt = await lastEndRecord(plan);
+    if (endAt >= 0) {
+        plan = layout(Math.ceil((endAt + 1 - (plan.size - ZIP_WINDOW)) / ss));
+        apply(plan);
+    }
+    // Both rules hold by construction. Checking them costs two small reads and turns a mistake into a failed write.
+    if ((await lastEndRecord(plan)) >= 0)
+        throw new Error('A ZIP end record is still within reach of ZIP readers');
+    if ((await bytesAt(plan, 0, Math.min(1024, plan.size))).includes('%PDF-'))
+        throw new Error('A PDF header is within the first 1024 bytes');
+    const { fatSectors, difatSectors, dirStart, miniFatStart } = plan;
+    const fatStart = 0;
+    const difatStart = fatSectors;
+    const fat = fatOf(plan);
+    const header = new Bytes(ss);
+    Buffer.from('d0cf11e0a1b11ae1', 'hex').copy(header.b, 0);
+    header.u16(0x18, 0x3e);
+    header.u16(0x1a, 3);
+    header.u16(0x1c, 0xfffe);
+    header.u16(0x1e, 9);
+    header.u16(0x20, 6);
+    header.u32(0x2c, fatSectors);
+    header.u32(0x30, dirStart);
+    header.u32(0x38, MINI_CUTOFF);
+    header.u32(0x3c, miniFatStart);
+    header.u32(0x40, miniFatSectors);
+    header.u32(0x44, difatSectors ? difatStart : END_OF_CHAIN);
+    header.u32(0x48, difatSectors);
+    for (let i = 0; i < HEADER_FAT; i++)
+        header.u32(0x4c + 4 * i, i < fatSectors ? fatStart + i : FREE);
+    await sink.write(header.b);
+    await sink.write(Buffer.from(fat.buffer));
+    if (difatSectors) {
+        const d = new Bytes(difatSectors * ss);
+        const rest = Math.max(0, fatSectors - HEADER_FAT);
+        for (let k = 0; k < difatSectors; k++) {
+            for (let i = 0; i < per - 1; i++) {
+                const n = k * (per - 1) + i;
+                d.u32(k * ss + 4 * i, n < rest ? fatStart + HEADER_FAT + n : FREE);
+            }
+            d.u32(k * ss + 4 * (per - 1), k === difatSectors - 1 ? END_OF_CHAIN : difatStart + k + 1);
+        }
+        await sink.write(d.b);
+    }
+    /** Copies a stream's bytes and pads them to `unit`. */
+    const copy = async (e, unit) => {
+        const node = e.node;
+        if (node?.kind !== 'stream')
+            return;
+        for (let at = 0; at < e.size; at += 262144) {
+            (0, errors_1.checkTime)(deadline);
+            const want = Math.min(262144, e.size - at);
+            const b = await node.source.read(at, want);
+            if (b.length !== want)
+                throw Object.assign(new Error(`A stream returned ${b.length} bytes where ${want} were expected`), { code: 'EIO' });
+            await sink.write(b);
+        }
+        const pad = (unit - (e.size % unit)) % unit;
+        if (pad)
+            await sink.write(new Uint8Array(pad));
+    };
+    for (const e of small)
+        await copy(e, MINI_SECTOR);
+    const miniPad = miniStreamSectors * ss - miniStreamSize;
+    if (miniPad)
+        await sink.write(new Uint8Array(miniPad));
+    for (const e of large)
+        await copy(e, ss);
+    await sink.write(directoryOf());
+    if (miniFatSectors)
+        await sink.write(Buffer.from(miniFat.buffer));
+    for (let i = 0; i < plan.pad; i++)
+        await sink.write(new Uint8Array(ss));
+}

package/dist/cfb.d.ts

@@ -0,0 +1,58 @@
+import { type ByteSource, OfficeDetail as D } from './types';
+/** The first eight bytes of every compound file. */
+export declare const CFB_SIGNATURE: Uint8Array<ArrayBuffer>;
+export interface CfbLimits {
+    entries: number;
+    decompressedBytes: number;
+    totalDecompressedBytes: number;
+}
+export interface CfbEntry {
+    /** The entry's position in the directory. */
+    id: number;
+    name: string;
+    kind: 'root' | 'storage' | 'stream';
+    /** The class id, as Windows writes a GUID, in upper case. */
+    clsid: string;
+    size: number;
+    parent?: CfbEntry;
+    children: CfbEntry[];
+}
+/** Something the reader saw that it does not refuse. Each is a strip finding, since a rewrite leaves the bytes out. */
+export interface CfbNote {
+    detail: D.HiddenData | D.TrailingBytes;
+    bytes: number;
+}
+/** A GUID as Windows shows it: the first three fields little-endian, upper case, without braces. */
+export declare function guid(b: Uint8Array, at?: number): string;
+/** An entry name with control and format characters written as \xNN, so a location can show it. */
+export declare const showName: (name: string) => string;
+/** The entry's path from the root, its names joined by "/", which no name may hold. */
+export declare function entryPath(e: CfbEntry): string;
+/**
+ * A compound file (MS-CFB), read from its header, its allocation tables and its directory. Every chain is followed as
+ * far as its stream needs and every sector has one owner, so two readers cannot read the file differently. Reading a
+ * stream maps its offsets through its chain; nothing is held but the tables.
+ */
+export declare class CompoundFile {
+    private readonly reader;
+    readonly sectorSize: number;
+    readonly root: CfbEntry;
+    /** Every entry the directory tree reaches, the root first, each storage before its children. */
+    readonly entries: CfbEntry[];
+    readonly notes: CfbNote[];
+    private readonly miniStream;
+    private readonly deadline;
+    private readonly streamChains;
+    private constructor();
+    /** The child of a storage with this name, compared ignoring case. */
+    child(storage: CfbEntry, name: string): CfbEntry | undefined;
+    /** Reads a compound file. The caller has seen its signature. */
+    static open(source: ByteSource, limits: CfbLimits, deadline?: number): Promise<CompoundFile>;
+    /** Bytes of the mini stream, by their offset in it. */
+    private readMini;
+    private readChain;
+    /** A random-access source over a stream's content. */
+    source(e: CfbEntry): ByteSource;
+    /** A stream's whole content. Callers read only streams whose size they bounded. */
+    bytes(e: CfbEntry): Promise<Uint8Array>;
+}