@patrickdk77/office-defuse 0.1.1 → 0.2.0

package/dist/formulas.js

@@ -1,6 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Quotes = void 0;
+exports.FunctionCalls = exports.Quotes = void 0;
+exports.riskyFunction = riskyFunction;
+exports.formulaCalls = formulaCalls;
+exports.biffCalls = biffCalls;
 exports.callsDde = callsDde;
 exports.fieldWords = fieldWords;
 /**
@@ -31,6 +34,159 @@ class Quotes {
     }
 }
 exports.Quotes = Quotes;
+/**
+ * Functions that reach outside the file when a formula is calculated: WEBSERVICE and IMAGE fetch a URL, RTD starts a
+ * COM server, CALL and REGISTER call into a DLL, and EXEC runs a program. A prefix such as `_xlfn.` or
+ * `COM.MICROSOFT.` names the same function.
+ */
+const FETCH = ['WEBSERVICE', 'IMAGE'];
+const RUN = ['RTD', 'CALL', 'REGISTER', 'REGISTER.ID', 'EXEC'];
+/** What a function a formula calls does outside the file, or undefined when it does nothing there. */
+function riskyFunction(name) {
+    const n = name.toUpperCase();
+    const is = (f) => n === f || n.endsWith(`.${f}`);
+    if (FETCH.some(is))
+        return 'fetch';
+    if (RUN.some(is))
+        return 'run';
+    return undefined;
+}
+/** The functions, outside quotes, that a formula's text calls and that reach outside the file, as its text arrives. */
+class FunctionCalls {
+    quotes = new Quotes();
+    word = '';
+    spaced = false;
+    found = new Map();
+    write(t) {
+        for (const c of t) {
+            if (!this.quotes.outside(c)) {
+                this.word = '';
+                continue;
+            }
+            if (/[A-Za-z0-9_.]/.test(c)) {
+                if (this.spaced)
+                    this.word = '';
+                this.spaced = false;
+                if (this.word.length < 64)
+                    this.word += c;
+            }
+            else if (c === ' ')
+                this.spaced = this.word !== '';
+            else {
+                if (c === '(' && this.word) {
+                    const kind = riskyFunction(this.word);
+                    if (kind)
+                        this.found.set(this.word.toUpperCase(), kind);
+                }
+                this.word = '';
+                this.spaced = false;
+            }
+        }
+    }
+}
+exports.FunctionCalls = FunctionCalls;
+/** The functions a formula's whole text calls that reach outside the file. */
+function formulaCalls(formula) {
+    const f = new FunctionCalls();
+    f.write(formula);
+    return f.found;
+}
+/** Built-in functions by their index in Excel's function table (MS-XLS 2.5.198.17): EXEC, REGISTER, CALL, REGISTER.ID and RTD. */
+const FTAB = new Map([
+    [110, 'EXEC'],
+    [149, 'REGISTER'],
+    [150, 'CALL'],
+    [267, 'REGISTER.ID'],
+    [379, 'RTD'],
+]);
+/**
+ * The functions a BIFF8 formula (MS-XLS 2.5.198) calls that reach outside the file: built-in ones by index, and
+ * add-in and newer ones by the name the formula names them with, such as `_xlfn.WEBSERVICE`. The walk stops at a
+ * token it does not know the size of.
+ */
+function biffCalls(rgce, nameOf) {
+    const found = new Map();
+    const u16 = (at) => rgce[at] | (rgce[at + 1] << 8);
+    const u32 = (at) => (rgce[at] | (rgce[at + 1] << 8) | (rgce[at + 2] << 16) | (rgce[at + 3] << 24)) >>> 0;
+    const add = (name) => {
+        const kind = name === undefined ? undefined : riskyFunction(name);
+        if (name !== undefined && kind)
+            found.set(name.toUpperCase(), kind);
+    };
+    for (let i = 0; i < rgce.length;) {
+        const ptg = rgce[i++];
+        if (ptg < 0x20) {
+            if (ptg === 0x01 || ptg === 0x02)
+                i += 4;
+            else if (ptg === 0x17)
+                i += 2 + (rgce[i] ?? 0) * ((rgce[i + 1] ?? 0) & 1 ? 2 : 1);
+            else if (ptg === 0x19) {
+                const grbit = rgce[i] ?? 0;
+                const w = u16(i + 1);
+                i += 3 + (grbit & 0x04 ? (w + 1) * 2 : 0);
+            }
+            else if (ptg === 0x1c || ptg === 0x1d)
+                i += 1;
+            else if (ptg === 0x1e)
+                i += 2;
+            else if (ptg === 0x1f)
+                i += 8;
+            else if (ptg < 0x03 || ptg > 0x16)
+                break;
+            continue;
+        }
+        switch (ptg & 0x1f) {
+            case 0x00:
+                i += 7;
+                break;
+            case 0x01:
+                add(FTAB.get(u16(i)));
+                i += 2;
+                break;
+            case 0x02:
+                add(FTAB.get(u16(i + 1) & 0x7fff));
+                i += 3;
+                break;
+            case 0x03:
+                add(nameOf({ kind: 'name', index: u32(i) }));
+                i += 4;
+                break;
+            case 0x04:
+            case 0x0a:
+            case 0x0c:
+                i += 4;
+                break;
+            case 0x05:
+            case 0x0b:
+            case 0x0d:
+                i += 8;
+                break;
+            case 0x06:
+            case 0x07:
+            case 0x08:
+                i += 6;
+                break;
+            case 0x09:
+                i += 2;
+                break;
+            case 0x19:
+                add(nameOf({ kind: 'namex', ixti: u16(i), index: u32(i + 2) }));
+                i += 6;
+                break;
+            case 0x1a:
+            case 0x1c:
+                i += 6;
+                break;
+            case 0x1b:
+            case 0x1d:
+                i += 10;
+                break;
+            default:
+                return found;
+        }
+    }
+    return found;
+}
 /** Whether an OpenDocument formula calls the DDE function. */
 function callsDde(formula) {
     const q = new Quotes();

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { inspectOffice, inspectOfficeSource } from './engine';
+export { disarmOffice, disarmOfficeSource, inspectOffice, inspectOfficeSource } from './engine';
 export { allFindingSpecs } from './findings';
-export { bufferSource, fileSource } from './io';
+export { bufferSink, bufferSource, fileSink, fileSource, writableSink } from './io';
+export { officePlugin } from './plugins';
 export { COMBINATIONS, DEFAULT_BANDS, scoreFindings } from './score';
 export * from './types';

package/dist/index.js

@@ -14,15 +14,22 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.scoreFindings = exports.DEFAULT_BANDS = exports.COMBINATIONS = exports.fileSource = exports.bufferSource = exports.allFindingSpecs = exports.inspectOfficeSource = exports.inspectOffice = void 0;
+exports.scoreFindings = exports.DEFAULT_BANDS = exports.COMBINATIONS = exports.officePlugin = exports.writableSink = exports.fileSource = exports.fileSink = exports.bufferSource = exports.bufferSink = exports.allFindingSpecs = exports.inspectOfficeSource = exports.inspectOffice = exports.disarmOfficeSource = exports.disarmOffice = void 0;
 var engine_1 = require("./engine");
+Object.defineProperty(exports, "disarmOffice", { enumerable: true, get: function () { return engine_1.disarmOffice; } });
+Object.defineProperty(exports, "disarmOfficeSource", { enumerable: true, get: function () { return engine_1.disarmOfficeSource; } });
 Object.defineProperty(exports, "inspectOffice", { enumerable: true, get: function () { return engine_1.inspectOffice; } });
 Object.defineProperty(exports, "inspectOfficeSource", { enumerable: true, get: function () { return engine_1.inspectOfficeSource; } });
 var findings_1 = require("./findings");
 Object.defineProperty(exports, "allFindingSpecs", { enumerable: true, get: function () { return findings_1.allFindingSpecs; } });
 var io_1 = require("./io");
+Object.defineProperty(exports, "bufferSink", { enumerable: true, get: function () { return io_1.bufferSink; } });
 Object.defineProperty(exports, "bufferSource", { enumerable: true, get: function () { return io_1.bufferSource; } });
+Object.defineProperty(exports, "fileSink", { enumerable: true, get: function () { return io_1.fileSink; } });
 Object.defineProperty(exports, "fileSource", { enumerable: true, get: function () { return io_1.fileSource; } });
+Object.defineProperty(exports, "writableSink", { enumerable: true, get: function () { return io_1.writableSink; } });
+var plugins_1 = require("./plugins");
+Object.defineProperty(exports, "officePlugin", { enumerable: true, get: function () { return plugins_1.officePlugin; } });
 var score_1 = require("./score");
 Object.defineProperty(exports, "COMBINATIONS", { enumerable: true, get: function () { return score_1.COMBINATIONS; } });
 Object.defineProperty(exports, "DEFAULT_BANDS", { enumerable: true, get: function () { return score_1.DEFAULT_BANDS; } });

package/dist/index.mjs

@@ -1,3 +1,3 @@
 import cjs from './index.js';
-export const { inspectOffice, inspectOfficeSource, allFindingSpecs, bufferSource, fileSource, COMBINATIONS, DEFAULT_BANDS, scoreFindings, OfficeCategory, OfficeDetail, OfficeRisk } = cjs;
+export const { disarmOffice, disarmOfficeSource, inspectOffice, inspectOfficeSource, allFindingSpecs, bufferSink, bufferSource, fileSink, fileSource, writableSink, officePlugin, COMBINATIONS, DEFAULT_BANDS, scoreFindings, OfficeCategory, OfficeDetail, OfficeRisk } = cjs;
 export default cjs;

package/dist/io.d.ts

@@ -1,4 +1,5 @@
-import type { ByteSource } from './types';
+import type { Writable } from 'node:stream';
+import type { ByteSink, ByteSource } from './types';
 /** A source over bytes already in memory. Reads return views, not copies. */
 export declare function bufferSource(bytes: Uint8Array): ByteSource;
 /** A source over a local file, read at offsets through one file handle. */
@@ -21,3 +22,63 @@ export declare class Reader {
     /** Yields the range in chunks without caching them. */
     chunks(offset: number, length: number, chunkSize?: number): AsyncGenerator<Uint8Array>;
 }
+/** Collects output in memory. */
+export declare function bufferSink(): ByteSink & {
+    result(): Uint8Array;
+    size(): number;
+};
+/** Writes to a local file. The file is created on the first write. */
+export declare function fileSink(filePath: string): ByteSink;
+/**
+ * Wraps any Node Writable, waiting for 'drain' when it applies backpressure. The stream's first error, or its
+ * closing before the end, fails the pending write and every later one.
+ */
+export declare function writableSink(stream: Writable): ByteSink;
+/** A private temporary directory, removed by cleanup(). It also keeps the run's first I/O error. */
+export declare class TempDir {
+    private readonly base;
+    private dir?;
+    private seq;
+    /** The first error from a temporary file, which the engine throws instead of a verdict on the file. */
+    ioError?: unknown;
+    constructor(base?: string);
+    file(suffix?: string): Promise<string>;
+    cleanup(): Promise<void>;
+}
+/**
+ * A sink that keeps what it is given in memory up to `threshold` bytes and in a temporary file past that, with the MD5
+ * of the bytes, which tells the output check that a file inside is the one a plugin returned.
+ */
+export declare class SpillSink implements ByteSink {
+    private readonly temp;
+    private readonly threshold;
+    private chunks;
+    private size;
+    private filePath?;
+    private handle?;
+    private readonly md5;
+    private hex?;
+    spilled: boolean;
+    constructor(temp: TempDir, threshold: number);
+    write(chunk: Uint8Array): Promise<void>;
+    close(): Promise<void>;
+    /** Closes the sink and deletes its temporary file, once nothing will read what it holds again. */
+    dispose(): Promise<void>;
+    get length(): number;
+    digest(): string;
+    /** A source over what was written. Call after close(). */
+    source(): ByteSource;
+    /** What was written, in chunks. Call after close(). */
+    read(chunkSize?: number): AsyncGenerator<Uint8Array>;
+}
+/**
+ * Copies a whole source, calling `checkTime` before each chunk. A read that returns more or fewer bytes than it asked
+ * for fails the copy, which would otherwise shift every byte after it.
+ */
+export declare function copyToSink(source: ByteSource, sink: ByteSink, checkTime?: () => void): Promise<void>;
+/** A source's bytes, from the start, in chunks. */
+export declare function chunksOf(source: ByteSource, size: number, chunkSize?: number): AsyncGenerator<Uint8Array>;
+/** Everything a spill sink holds, in memory. Call after close(). */
+export declare function readAll(sink: SpillSink): Promise<Uint8Array>;
+/** A source's bytes from `start`, `length` of them, in chunks. */
+export declare function rangeChunks(source: ByteSource, start: number, length: number, chunkSize?: number): AsyncGenerator<Uint8Array>;

package/dist/io.js

@@ -33,10 +33,20 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Reader = void 0;
+exports.SpillSink = exports.TempDir = exports.Reader = void 0;
 exports.bufferSource = bufferSource;
 exports.fileSource = fileSource;
+exports.bufferSink = bufferSink;
+exports.fileSink = fileSink;
+exports.writableSink = writableSink;
+exports.copyToSink = copyToSink;
+exports.chunksOf = chunksOf;
+exports.readAll = readAll;
+exports.rangeChunks = rangeChunks;
+const crypto = __importStar(require("node:crypto"));
 const fsp = __importStar(require("node:fs/promises"));
+const os = __importStar(require("node:os"));
+const path = __importStar(require("node:path"));
 /** A source over bytes already in memory. Reads return views, not copies. */
 function bufferSource(bytes) {
     return {
@@ -137,3 +147,237 @@ class Reader {
     }
 }
 exports.Reader = Reader;
+/** Collects output in memory. */
+function bufferSink() {
+    const chunks = [];
+    let size = 0;
+    return {
+        async write(chunk) {
+            chunks.push(Buffer.from(chunk));
+            size += chunk.length;
+        },
+        async close() {
+            // Nothing to release. The chunks stay for result().
+        },
+        result: () => Buffer.concat(chunks),
+        size: () => size,
+    };
+}
+/** FileHandle.write may write less than asked, for example at a file size limit; the next write then reports why. */
+async function writeAll(handle, chunk) {
+    for (let done = 0; done < chunk.length;)
+        done += (await handle.write(chunk, done, chunk.length - done)).bytesWritten;
+}
+/** Writes to a local file. The file is created on the first write. */
+function fileSink(filePath) {
+    let handle;
+    return {
+        async write(chunk) {
+            handle ??= await fsp.open(filePath, 'w');
+            await writeAll(handle, chunk);
+        },
+        async close() {
+            handle ??= await fsp.open(filePath, 'w');
+            await handle.close();
+        },
+        async abort() {
+            const h = handle;
+            handle = undefined;
+            if (!h)
+                return;
+            // A partial regular file goes. abort() never unlinks a device or pipe the caller named.
+            const partial = (await h.stat().catch(() => undefined))?.isFile();
+            await h.close().catch(() => {
+                // abort() runs after a failure, which is the error to report.
+            });
+            if (partial)
+                await fsp.rm(filePath, { force: true });
+        },
+    };
+}
+/**
+ * Wraps any Node Writable, waiting for 'drain' when it applies backpressure. The stream's first error, or its
+ * closing before the end, fails the pending write and every later one.
+ */
+function writableSink(stream) {
+    let failure;
+    const pending = new Set();
+    const fail = (e) => {
+        failure ??= e;
+        for (const reject of pending)
+            reject(failure);
+        pending.clear();
+    };
+    // Node emits some errors after the write callback, and an 'error' with no listener crashes the process, so this
+    // listener stays for the stream's whole life.
+    stream.on('error', fail);
+    stream.on('close', () => {
+        if (!stream.writableFinished)
+            fail(stream.errored ?? new Error('The output stream closed before all data was written'));
+    });
+    const settle = (start) => new Promise((resolve, reject) => {
+        if (failure)
+            return reject(failure);
+        if (stream.destroyed)
+            return reject(stream.errored ?? new Error('The output stream was destroyed'));
+        pending.add(reject);
+        start(err => {
+            pending.delete(reject);
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+    });
+    return {
+        write: chunk => settle(done => (stream.write(chunk) ? done() : stream.once('drain', () => done()))),
+        close: () => settle(done => stream.end((err) => done(err))),
+        // The reader sees an error instead of an end, so it cannot mistake a partial output for a whole one.
+        abort: async (error) => {
+            stream.destroy(error instanceof Error ? error : new Error(String(error)));
+        },
+    };
+}
+/** A private temporary directory, removed by cleanup(). It also keeps the run's first I/O error. */
+class TempDir {
+    base;
+    // The pending mkdtemp is shared, so concurrent first calls make one directory and cleanup() removes it.
+    dir;
+    seq = 0;
+    /** The first error from a temporary file, which the engine throws instead of a verdict on the file. */
+    ioError;
+    constructor(base = os.tmpdir()) {
+        this.base = base;
+    }
+    async file(suffix = '.bin') {
+        this.dir ??= fsp.mkdtemp(path.join(this.base, 'office-defuse-'));
+        return path.join(await this.dir, `${this.seq++}${suffix}`);
+    }
+    async cleanup() {
+        const dir = await this.dir?.catch(() => undefined);
+        this.dir = undefined;
+        if (dir)
+            await fsp.rm(dir, { recursive: true, force: true });
+    }
+}
+exports.TempDir = TempDir;
+/**
+ * A sink that keeps what it is given in memory up to `threshold` bytes and in a temporary file past that, with the MD5
+ * of the bytes, which tells the output check that a file inside is the one a plugin returned.
+ */
+class SpillSink {
+    temp;
+    threshold;
+    chunks = [];
+    size = 0;
+    filePath;
+    handle;
+    md5 = crypto.createHash('md5');
+    hex;
+    spilled = false;
+    constructor(temp, threshold) {
+        this.temp = temp;
+        this.threshold = threshold;
+    }
+    async write(chunk) {
+        this.md5.update(chunk);
+        this.size += chunk.length;
+        if (!this.handle && this.size <= this.threshold) {
+            this.chunks.push(Buffer.from(chunk));
+            return;
+        }
+        try {
+            if (!this.handle) {
+                this.filePath = await this.temp.file('.spill');
+                this.handle = await fsp.open(this.filePath, 'w');
+                this.spilled = true;
+                for (const c of this.chunks)
+                    await writeAll(this.handle, c);
+                this.chunks = [];
+            }
+            await writeAll(this.handle, chunk);
+        }
+        catch (e) {
+            this.temp.ioError ??= e;
+            throw e;
+        }
+    }
+    async close() {
+        await this.handle?.close();
+        this.handle = undefined;
+    }
+    /** Closes the sink and deletes its temporary file, once nothing will read what it holds again. */
+    async dispose() {
+        await this.close();
+        this.chunks = [];
+        const file = this.filePath;
+        this.filePath = undefined;
+        if (file === undefined)
+            return;
+        try {
+            await fsp.rm(file, { force: true });
+        }
+        catch (e) {
+            this.temp.ioError ??= e;
+            throw e;
+        }
+    }
+    get length() {
+        return this.size;
+    }
+    digest() {
+        this.hex ??= this.md5.digest('hex');
+        return this.hex;
+    }
+    /** A source over what was written. Call after close(). */
+    source() {
+        return this.filePath ? fileSource(this.filePath) : bufferSource(Buffer.concat(this.chunks));
+    }
+    /** What was written, in chunks. Call after close(). */
+    async *read(chunkSize = 262144) {
+        const src = this.source();
+        // A consumer that stops early, such as a failed output write, still closes the file.
+        try {
+            const total = await src.size();
+            for (let pos = 0; pos < total; pos += chunkSize)
+                yield await src.read(pos, Math.min(chunkSize, total - pos));
+        }
+        finally {
+            await src.close?.();
+        }
+    }
+}
+exports.SpillSink = SpillSink;
+/**
+ * Copies a whole source, calling `checkTime` before each chunk. A read that returns more or fewer bytes than it asked
+ * for fails the copy, which would otherwise shift every byte after it.
+ */
+async function copyToSink(source, sink, checkTime) {
+    const total = await source.size();
+    const chunk = 262144;
+    for (let pos = 0; pos < total; pos += chunk) {
+        checkTime?.();
+        const want = Math.min(chunk, total - pos);
+        const b = await source.read(pos, want);
+        if (b.length !== want)
+            throw Object.assign(new Error(`The source returned ${b.length} bytes at offset ${pos} where ${want} were expected`), { code: 'EIO' });
+        await sink.write(b);
+    }
+}
+/** A source's bytes, from the start, in chunks. */
+async function* chunksOf(source, size, chunkSize = 262144) {
+    for (let at = 0; at < size; at += chunkSize)
+        yield await source.read(at, Math.min(chunkSize, size - at));
+}
+/** Everything a spill sink holds, in memory. Call after close(). */
+async function readAll(sink) {
+    const parts = [];
+    for await (const c of sink.read())
+        parts.push(c);
+    return Buffer.concat(parts);
+}
+/** A source's bytes from `start`, `length` of them, in chunks. */
+async function* rangeChunks(source, start, length, chunkSize = 262144) {
+    for (let at = 0; at < length; at += chunkSize)
+        yield await source.read(start + at, Math.min(chunkSize, length - at));
+}

package/dist/links.d.ts

@@ -24,3 +24,30 @@ export declare const isLocalTarget: (rawTarget: string) => boolean;
 export declare const isInsidePackage: (rawHref: string) => boolean;
 /** Whether an OOXML relationship target is not a part name, whatever TargetMode says: a scheme, a drive or a network path. */
 export declare const isAbsoluteTarget: (rawTarget: string) => boolean;
+/**
+ * The hosts a label names, as a lookup: has() answers whether a host is one of them or a subdomain of one, or one of
+ * them is a subdomain of the host. No public-suffix list is needed: evil.co.uk is not under mybank.co.uk. The same
+ * comparison as pdf-defuse's.
+ */
+export declare class LabelSites {
+    private readonly hosts;
+    /** Every domain some label host is a subdomain of. */
+    private readonly parents;
+    constructor(names: string[]);
+    get size(): number;
+    has(host: string): boolean;
+}
+/**
+ * The site a label names when the label is itself an address: a web URL, a mail address, or a host with or without a
+ * path that starts with www. or ends in a known top-level domain. Text that only mentions an address, an Excel
+ * function name and a file name name no site. Excel's function names are all capitals, as typed hosts never are, so
+ * a bare host in capitals counts only after WWW.
+ */
+export declare function labelSite(raw: string): string | undefined;
+/**
+ * The first label of a safe link that is an address, and an address of another site than the one the link opens, or
+ * undefined. A label is text the reader sees for the link: its text, its tooltip, a display name. A subdomain or a
+ * parent of the label's site counts as the same site, as in pdf-defuse. A target that fails on its own gets its own
+ * finding instead.
+ */
+export declare function mismatchedLabel(target: string, labels: ReadonlyArray<string | undefined>): string | undefined;