@patrickdk77/office-defuse 0.0.0-stage → 0.1.1

package/dist/crc32.js

@@ -0,0 +1,58 @@
+"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.crc32 = void 0;
+exports.tableCrc32 = tableCrc32;
+const zlib = __importStar(require("node:zlib"));
+const TABLE = new Uint32Array(256);
+for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++)
+        c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    TABLE[n] = c >>> 0;
+}
+/** Continues a CRC-32, the one ZIP uses, over `bytes`, with a lookup table. Start from 0. */
+function tableCrc32(bytes, crc = 0) {
+    let c = ~crc >>> 0;
+    for (const b of bytes)
+        c = TABLE[(c ^ b) & 0xff] ^ (c >>> 8);
+    return ~c >>> 0;
+}
+/**
+ * Continues a CRC-32, the one ZIP uses, over `bytes`. Start from 0. This is zlib.crc32 where Node has it, about 50
+ * times faster, and the table otherwise. Node 18 and early releases of Node 20 and 22 lack it. The choice is made
+ * once, when the module loads.
+ */
+exports.crc32 = zlib.crc32 ?? tableCrc32;

package/dist/engine.d.ts

@@ -0,0 +1,5 @@
+import { type ByteSource, type OfficeInspection, type OfficeOptions } from './types';
+/** Inspects an Office or OpenDocument file without changing it. The source is closed when the run ends. */
+export declare function inspectOfficeSource(source: ByteSource, options?: OfficeOptions): Promise<OfficeInspection>;
+/** Inspects Office or OpenDocument bytes. */
+export declare function inspectOffice(bytes: Uint8Array, options?: OfficeOptions): Promise<OfficeInspection>;

package/dist/engine.js

@@ -0,0 +1,200 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inspectOfficeSource = inspectOfficeSource;
+exports.inspectOffice = inspectOffice;
+const cfb_1 = require("./cfb");
+const context_1 = require("./context");
+const errors_1 = require("./errors");
+const findings_1 = require("./findings");
+const io_1 = require("./io");
+const ole_1 = require("./ole");
+const package_1 = require("./package");
+const rtf_1 = require("./rtf");
+const score_1 = require("./score");
+const types_1 = require("./types");
+const zip_1 = require("./zip");
+const DEFAULT_LIMITS = {
+    entries: 10_000,
+    decompressedBytes: 512 * 1024 * 1024,
+    totalDecompressedBytes: 2 * 1024 * 1024 * 1024,
+    xmlDepth: 256,
+    xmlTokenSize: 16 * 1024 * 1024,
+    xmlEntityDepth: 16,
+    xmlEntityExpansions: 100_000,
+    xmlEntitySize: 16 * 1024 * 1024,
+    rtfDepth: 256,
+};
+function resolveLimits(given = {}) {
+    return {
+        entries: given.entries ?? DEFAULT_LIMITS.entries,
+        decompressedBytes: given.decompressedBytes ?? DEFAULT_LIMITS.decompressedBytes,
+        totalDecompressedBytes: given.totalDecompressedBytes ?? DEFAULT_LIMITS.totalDecompressedBytes,
+        xmlDepth: given.xmlDepth ?? DEFAULT_LIMITS.xmlDepth,
+        xmlTokenSize: given.xmlTokenSize ?? DEFAULT_LIMITS.xmlTokenSize,
+        xmlEntityDepth: given.xmlEntityDepth ?? DEFAULT_LIMITS.xmlEntityDepth,
+        xmlEntityExpansions: given.xmlEntityExpansions ?? DEFAULT_LIMITS.xmlEntityExpansions,
+        xmlEntitySize: given.xmlEntitySize ?? DEFAULT_LIMITS.xmlEntitySize,
+        rtfDepth: given.rtfDepth ?? DEFAULT_LIMITS.rtfDepth,
+        fileSize: given.fileSize,
+        timeMs: given.timeMs,
+    };
+}
+/**
+ * `incomplete` marks a run that stopped before it read the whole package. It is rejected without a score, whatever
+ * the actions say, because an override can make the finding that stopped it look harmless.
+ */
+function finish(findings, options, incomplete, format) {
+    const named = { format: format?.format ?? '', mimeType: format?.mimeType ?? '' };
+    if (incomplete)
+        return { status: 'rejected', score: null, risk: types_1.OfficeRisk.Unknown, findings, ...named };
+    const rejected = findings.some(f => f.action === 'reject');
+    const strippable = findings.some(f => f.action === 'strip');
+    const { score, risk } = (0, score_1.scoreFindings)(findings, options);
+    return { status: rejected ? 'rejected' : strippable ? 'strippable' : 'clean', score, risk, findings, ...named };
+}
+/**
+ * Wraps the source for one run. A read that returns more or fewer bytes than the source's size allows fails with
+ * code EIO, since the reader would take the shifted bytes for the file. Any error the source throws is kept, and the
+ * engine throws it instead of a verdict on the file.
+ */
+function guarded(source) {
+    let size = 0;
+    const g = {
+        size: async () => {
+            try {
+                size = await source.size();
+                return size;
+            }
+            catch (e) {
+                g.failure ??= e;
+                throw e;
+            }
+        },
+        read: async (offset, length) => {
+            try {
+                const b = await source.read(offset, length);
+                const want = Math.max(0, Math.min(length, size - offset));
+                if (b.length !== want)
+                    throw Object.assign(new Error(`The source returned ${b.length} bytes at offset ${offset} where ${want} were expected`), { code: 'EIO' });
+                return b;
+            }
+            catch (e) {
+                g.failure ??= e;
+                throw e;
+            }
+        },
+    };
+    return g;
+}
+const ambiguous = (reason) => new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.AmbiguousFormat, `The file is ${reason}`, { reason });
+/**
+ * Reads the file's container. A file that starts with the compound file signature is read as one, and one that
+ * starts with {\rt is RTF, which is how Word tells them. The ZIP reader runs too, from the end: a file both read is
+ * ambiguous, since Office goes by the first bytes and a ZIP reader by the last. A compound file that does not read is
+ * a ZIP archive with data in front, if the ZIP reader read one. Word reads any file that starts with {\rt as RTF, so
+ * that does not fail.
+ */
+async function openContainer(src, size, limits, settings) {
+    const head = await src.read(0, Math.min(8, size));
+    const cfbSignature = head.length === 8 && head.every((b, i) => b === cfb_1.CFB_SIGNATURE[i]);
+    const rtfSignature = Buffer.from(head.subarray(0, 4)).toString('latin1') === '{\\rt';
+    const probe = cfbSignature || rtfSignature
+        ? await zip_1.ZipArchive.open(src, limits, settings.deadline).catch((e) => {
+            if (e instanceof errors_1.StopError)
+                return undefined;
+            throw e;
+        })
+        : undefined;
+    if (rtfSignature) {
+        if (probe)
+            throw ambiguous('both RTF and a ZIP archive');
+        return { kind: 'rtf' };
+    }
+    if (cfbSignature) {
+        try {
+            const cfb = await cfb_1.CompoundFile.open(src, settings, settings.deadline);
+            if (probe)
+                throw ambiguous('both a compound file and a ZIP archive');
+            return { kind: 'cfb', cfb };
+        }
+        catch (e) {
+            if (!probe || !(e instanceof errors_1.StopError) || e.category !== types_1.OfficeCategory.Container)
+                throw e;
+        }
+    }
+    return { kind: 'zip', zip: probe ?? (await zip_1.ZipArchive.open(src, limits, settings.deadline)) };
+}
+/** Inspects an Office or OpenDocument file without changing it. The source is closed when the run ends. */
+async function inspectOfficeSource(source, options = {}) {
+    const limits = resolveLimits(options.limits);
+    const deadline = limits.timeMs !== undefined ? Date.now() + limits.timeMs : undefined;
+    const factory = new findings_1.FindingFactory(options.actionOverrides);
+    const findings = [];
+    const src = guarded(source);
+    const settings = {
+        entries: limits.entries,
+        decompressedBytes: limits.decompressedBytes,
+        totalDecompressedBytes: limits.totalDecompressedBytes,
+        rtfDepth: limits.rtfDepth,
+        deadline,
+        password: options.password,
+    };
+    const ctx = new context_1.RunContext(factory, {
+        depth: limits.xmlDepth,
+        tokenSize: limits.xmlTokenSize,
+        entityDepth: limits.xmlEntityDepth,
+        entityExpansions: limits.xmlEntityExpansions,
+        entitySize: limits.xmlEntitySize,
+    }, settings);
+    try {
+        const size = await src.size();
+        if (limits.fileSize !== undefined && size > limits.fileSize)
+            throw new errors_1.StopError(types_1.OfficeCategory.Limit, types_1.OfficeDetail.FileSize, `${size} bytes`, { size, limit: limits.fileSize });
+        (0, errors_1.checkTime)(deadline);
+        const container = await openContainer(src, size, limits, settings);
+        if (container.kind === 'rtf')
+            await (0, rtf_1.inspectRtf)(ctx, src, size);
+        else if (container.kind === 'cfb') {
+            for (const n of container.cfb.notes)
+                findings.push(factory.make(types_1.OfficeCategory.Container, n.detail, undefined, { bytes: n.bytes }));
+            await (0, ole_1.inspectCompound)(ctx, container.cfb);
+        }
+        else {
+            const zip = container.zip;
+            for (const n of zip.notes)
+                findings.push(factory.make(types_1.OfficeCategory.Container, n.detail, undefined, { bytes: n.bytes }));
+            await (0, package_1.inspectPackage)(ctx.withZip(zip));
+        }
+        findings.push(...ctx.findings);
+        return finish(findings, options, false, ctx.format);
+    }
+    catch (e) {
+        if (src.failure !== undefined)
+            throw src.failure;
+        findings.push(...ctx.findings);
+        if (e instanceof errors_1.StopError) {
+            findings.push(factory.make(e.category, e.detail, e.location ?? (typeof e.data?.name === 'string' ? e.data.name : undefined), { ...e.data, reason: e.data?.reason ?? e.message }));
+        }
+        else if (e?.code === 'DEFUSE_LIMIT') {
+            // The family's time limit, from this package or any other.
+            findings.push(factory.make(types_1.OfficeCategory.Limit, types_1.OfficeDetail.Time));
+        }
+        else {
+            // Anything unexpected rejects the file rather than escaping as an exception.
+            findings.push(factory.make(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unreadable, undefined, { reason: String(e?.message ?? e).slice(0, 200) }));
+        }
+        return finish(findings, options, true, ctx.format);
+    }
+    finally {
+        try {
+            await source.close?.();
+        }
+        catch {
+            // The verdict stands whether or not the source closes.
+        }
+    }
+}
+/** Inspects Office or OpenDocument bytes. */
+async function inspectOffice(bytes, options = {}) {
+    return inspectOfficeSource((0, io_1.bufferSource)(bytes), options);
+}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+import type { OfficeCategory, OfficeDetail } from './types';
+/** The run passed its deadline. The code makes every package of the family pass it up instead of treating it as one plugin failing. */
+export declare class TimeLimitError extends Error {
+    readonly code = "DEFUSE_LIMIT";
+    readonly limit = "time";
+}
+/**
+ * A refusal or a limit that stops the run. The engine turns it into the finding it names and rejects the file with
+ * no score, whatever the overrides say.
+ */
+export declare class StopError extends Error {
+    readonly category: OfficeCategory;
+    readonly detail: OfficeDetail;
+    readonly data?: Record<string, string | number> | undefined;
+    readonly location?: string | undefined;
+    constructor(category: OfficeCategory, detail: OfficeDetail, message: string, data?: Record<string, string | number> | undefined, location?: string | undefined);
+}
+/** Throws the time limit once `deadline`, a Date.now() value, has passed. */
+export declare function checkTime(deadline: number | undefined): void;

package/dist/errors.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StopError = exports.TimeLimitError = void 0;
+exports.checkTime = checkTime;
+/** The run passed its deadline. The code makes every package of the family pass it up instead of treating it as one plugin failing. */
+class TimeLimitError extends Error {
+    code = 'DEFUSE_LIMIT';
+    limit = 'time';
+}
+exports.TimeLimitError = TimeLimitError;
+/**
+ * A refusal or a limit that stops the run. The engine turns it into the finding it names and rejects the file with
+ * no score, whatever the overrides say.
+ */
+class StopError extends Error {
+    category;
+    detail;
+    data;
+    location;
+    constructor(category, detail, message, data, location) {
+        super(message);
+        this.category = category;
+        this.detail = detail;
+        this.data = data;
+        this.location = location;
+    }
+}
+exports.StopError = StopError;
+/** Throws the time limit once `deadline`, a Date.now() value, has passed. */
+function checkTime(deadline) {
+    if (deadline !== undefined && Date.now() > deadline)
+        throw new TimeLimitError('Time limit exceeded');
+}

package/dist/fields.d.ts

@@ -0,0 +1,29 @@
+import { type RunContext } from './context';
+/**
+ * Reports a Word field by its code. A field whose name holds the content of an external entity has a type the file
+ * does not say, as one whose name another field builds does.
+ */
+export declare function evaluateField(ctx: RunContext, location: string, code: string, computed: boolean): void;
+/**
+ * Word field codes, followed through nested fields as the text of a document arrives: a field begins, its code
+ * comes, a separator starts its result, and it ends. Each format says where those marks are.
+ */
+export declare class FieldStack {
+    private readonly ctx;
+    private readonly location;
+    private readonly stack;
+    constructor(ctx: RunContext, location: string);
+    /** A field starts. One that starts before its parent's code has a word in it makes that code at run time. */
+    begin(): void;
+    /** A field that is all code, such as OOXML's fldSimple. */
+    simple(code: string): void;
+    separate(): void;
+    end(): void;
+    /** Whether a field's code is being read now. */
+    get inCode(): boolean;
+    /** Text of the innermost field's code. White space before the first word counts for nothing, so no amount of it can push the field's name out. */
+    text(t: string): void;
+    /** A document can end inside a field. Word still reads the code it has. */
+    finish(): void;
+    private nest;
+}

package/dist/fields.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldStack = void 0;
+exports.evaluateField = evaluateField;
+const context_1 = require("./context");
+const formulas_1 = require("./formulas");
+const links_1 = require("./links");
+const types_1 = require("./types");
+const xml_1 = require("./xml");
+/** How much of a field code is kept, counted from its first word, which names the field. */
+const MAX_FIELD_CODE = 4096;
+/**
+ * Reports a Word field by its code. A field whose name holds the content of an external entity has a type the file
+ * does not say, as one whose name another field builds does.
+ */
+function evaluateField(ctx, location, code, computed) {
+    const data = { code: (0, context_1.clip)(code.trim()) };
+    const words = (0, formulas_1.fieldWords)(code);
+    const first = words[0]?.text ?? '';
+    const entity = (0, xml_1.unknownEntity)(first);
+    if (computed || entity !== undefined)
+        ctx.report(types_1.OfficeCategory.Field, types_1.OfficeDetail.Computed, location, entity === undefined ? data : { ...data, entity: (0, context_1.clip)(entity) });
+    const name = first.toUpperCase();
+    // An argument comes before any switch, and a switch is an unquoted word starting with a backslash.
+    const switchAt = words.findIndex(w => !w.quoted && w.text.startsWith('\\'));
+    const arg = (n) => (words[n] !== undefined && (switchAt < 0 || n < switchAt) ? words[n].text : undefined);
+    if (name === 'DDE' || name === 'DDEAUTO')
+        ctx.report(types_1.OfficeCategory.Dde, types_1.OfficeDetail.Field, location, data);
+    else if (name === 'MACROBUTTON')
+        ctx.report(types_1.OfficeCategory.Field, types_1.OfficeDetail.Macrobutton, location, { ...data, macro: (0, context_1.clip)(words[1]?.text ?? '') });
+    else if (name === 'INCLUDETEXT' || name === 'INCLUDEPICTURE' || name === 'IMPORT' || name === 'LINK') {
+        const target = arg(name === 'LINK' ? 2 : 1);
+        if (target === undefined)
+            ctx.report(types_1.OfficeCategory.External, types_1.OfficeDetail.Include, location, data);
+        else
+            ctx.external(types_1.OfficeDetail.Include, target, location, data, 'field');
+    }
+    else if (name === 'HYPERLINK') {
+        const target = arg(1);
+        if (target !== undefined && !(0, links_1.isFragment)(target))
+            ctx.link(target, location, { ...data, source: 'HYPERLINK field' });
+    }
+}
+/**
+ * Word field codes, followed through nested fields as the text of a document arrives: a field begins, its code
+ * comes, a separator starts its result, and it ends. Each format says where those marks are.
+ */
+class FieldStack {
+    ctx;
+    location;
+    stack = [];
+    constructor(ctx, location) {
+        this.ctx = ctx;
+        this.location = location;
+    }
+    /** A field starts. One that starts before its parent's code has a word in it makes that code at run time. */
+    begin() {
+        this.nest();
+        this.stack.push({ code: '', inCode: true, computed: false });
+    }
+    /** A field that is all code, such as OOXML's fldSimple. */
+    simple(code) {
+        this.nest();
+        evaluateField(this.ctx, this.location, code, false);
+    }
+    separate() {
+        const top = this.stack[this.stack.length - 1];
+        if (top)
+            top.inCode = false;
+    }
+    end() {
+        const f = this.stack.pop();
+        if (f)
+            evaluateField(this.ctx, this.location, f.code, f.computed);
+    }
+    /** Whether a field's code is being read now. */
+    get inCode() {
+        return this.stack[this.stack.length - 1]?.inCode === true;
+    }
+    /** Text of the innermost field's code. White space before the first word counts for nothing, so no amount of it can push the field's name out. */
+    text(t) {
+        const top = this.stack[this.stack.length - 1];
+        if (top?.inCode && top.code.length < MAX_FIELD_CODE)
+            top.code = top.code ? top.code + t : t.trimStart();
+    }
+    /** A document can end inside a field. Word still reads the code it has. */
+    finish() {
+        for (let f = this.stack.pop(); f; f = this.stack.pop())
+            evaluateField(this.ctx, this.location, f.code, f.computed);
+    }
+    nest() {
+        const top = this.stack[this.stack.length - 1];
+        if (top?.inCode && top.code === '')
+            top.computed = true;
+    }
+}
+exports.FieldStack = FieldStack;

package/dist/findings.d.ts

@@ -0,0 +1,25 @@
+import { OfficeCategory as C, OfficeDetail as D, type OfficeActionOverride, type OfficeFinding, type OfficeFindingAction } from './types';
+interface Spec {
+    action: OfficeFindingAction;
+    /**
+     * May contain <first|second> choices, which take the first alternative whose {key} values from the data are all
+     * set and not empty, or that names none. A value has control and format characters replaced by "?" and is cut to
+     * 60 characters.
+     */
+    description: string;
+    weight: number;
+}
+/** The built-in spec for a kind of finding, or undefined for a kind office-defuse does not make, such as one from another package. */
+export declare function findingSpec(category: string, detail: string): Spec | undefined;
+/** Every category and detail pair office-defuse makes, with its default action, description and score weight. */
+export declare function allFindingSpecs(): Array<{
+    category: C;
+    detail: D;
+} & Spec>;
+export declare class FindingFactory {
+    private readonly overrides;
+    constructor(overrides?: OfficeActionOverride[]);
+    private actionFor;
+    make(category: C, detail: D, location?: string, data?: Record<string, string | number>): OfficeFinding;
+}
+export {};