@patrickdk77/office-defuse 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,247 @@
+/** High-level kind of a finding. */
+export declare enum OfficeCategory {
+    Container = "CONTAINER",
+    Xml = "XML",
+    Limit = "LIMIT",
+    Package = "PACKAGE",
+    Encrypted = "ENCRYPTED",
+    Macro = "MACRO",
+    Ui = "UI",
+    Action = "ACTION",
+    Dde = "DDE",
+    Field = "FIELD",
+    External = "EXTERNAL",
+    Link = "LINK",
+    Embedded = "EMBEDDED",
+    Control = "CONTROL"
+}
+/** Exact variant of a finding. Some details appear under more than one category. */
+export declare enum OfficeDetail {
+    NotZip = "NOT_ZIP",
+    AmbiguousEnd = "AMBIGUOUS_END",
+    MultiDisk = "MULTI_DISK",
+    DirectoryMismatch = "DIRECTORY_MISMATCH",
+    OutOfRange = "OUT_OF_RANGE",
+    Overlap = "OVERLAP",
+    HeaderMismatch = "HEADER_MISMATCH",
+    DuplicateName = "DUPLICATE_NAME",
+    UnsafeName = "UNSAFE_NAME",
+    NameEncoding = "NAME_ENCODING",
+    EncryptedEntry = "ENCRYPTED_ENTRY",
+    UnsupportedMethod = "UNSUPPORTED_METHOD",
+    Zip64Mismatch = "ZIP64_MISMATCH",
+    BadExtraField = "BAD_EXTRA_FIELD",
+    DataError = "DATA_ERROR",
+    LeadingBytes = "LEADING_BYTES",
+    HiddenData = "HIDDEN_DATA",
+    TrailingBytes = "TRAILING_BYTES",
+    Doctype = "DOCTYPE",
+    InternalSubset = "INTERNAL_SUBSET",
+    ExternalEntity = "EXTERNAL_ENTITY",
+    Malformed = "MALFORMED",
+    Encoding = "ENCODING",
+    FileSize = "FILE_SIZE",
+    EntryCount = "ENTRY_COUNT",
+    DecompressedSize = "DECOMPRESSED_SIZE",
+    TotalDecompressedSize = "TOTAL_DECOMPRESSED_SIZE",
+    XmlDepth = "XML_DEPTH",
+    XmlTokenSize = "XML_TOKEN_SIZE",
+    XmlEntityDepth = "XML_ENTITY_DEPTH",
+    XmlEntityExpansions = "XML_ENTITY_EXPANSIONS",
+    XmlEntitySize = "XML_ENTITY_SIZE",
+    Time = "TIME",
+    Unrecognized = "UNRECOGNIZED",
+    AmbiguousFormat = "AMBIGUOUS_FORMAT",
+    Unreadable = "UNREADABLE",
+    DuplicateEntry = "DUPLICATE_ENTRY",
+    UntypedPart = "UNTYPED_PART",
+    UnreferencedPart = "UNREFERENCED_PART",
+    OdfLayout = "ODF_LAYOUT",
+    PasswordRequired = "PASSWORD_REQUIRED",
+    VbaProject = "VBA_PROJECT",
+    XlmMacrosheet = "XLM_MACROSHEET",
+    OdfBasic = "ODF_BASIC",
+    OdfScripts = "ODF_SCRIPTS",
+    OdfDialogs = "ODF_DIALOGS",
+    EventOnOpen = "EVENT_ON_OPEN",
+    Event = "EVENT",
+    Link = "LINK",
+    Ribbon = "RIBBON",
+    Callback = "CALLBACK",
+    OdfConfiguration = "ODF_CONFIGURATION",
+    RunProgram = "RUN_PROGRAM",
+    OleVerb = "OLE_VERB",
+    Field = "FIELD",
+    Formula = "FORMULA",
+    Macrobutton = "MACROBUTTON",
+    Computed = "COMPUTED",
+    Template = "TEMPLATE",
+    Object = "OBJECT",
+    Image = "IMAGE",
+    Frame = "FRAME",
+    Include = "INCLUDE",
+    Workbook = "WORKBOOK",
+    Reload = "RELOAD",
+    Other = "OTHER",
+    LocalFile = "LOCAL_FILE",
+    Safe = "SAFE",
+    FileUrl = "FILE_URL",
+    NetworkPath = "NETWORK_PATH",
+    DataUrl = "DATA_URL",
+    ScriptUrl = "SCRIPT_URL",
+    OtherScheme = "OTHER_SCHEME",
+    Credentials = "CREDENTIALS",
+    IpHost = "IP_HOST",
+    LookalikeHost = "LOOKALIKE_HOST",
+    EncodedHost = "ENCODED_HOST",
+    Relative = "RELATIVE",
+    OleObject = "OLE_OBJECT",
+    Package = "PACKAGE",
+    OleFile = "OLE_FILE",
+    Applet = "APPLET",
+    Plugin = "PLUGIN",
+    ActiveX = "ACTIVEX"
+}
+export type OfficeFindingAction = 'reject' | 'strip' | 'info';
+/**
+ * A finding as any package of the defuse family reports it. Category and detail are plain strings, since the string
+ * enums of two packages never match each other.
+ */
+export interface DefuseFinding {
+    category: string;
+    detail: string;
+    /** Plain sentence, safe to show the uploader. */
+    description: string;
+    /** Default action after any caller override. */
+    action: 'reject' | 'strip' | 'info';
+    /** Where in the file, such as a part name or a relationship. */
+    location?: string;
+    /** Extra values: the target, the field code, the content type, counts. */
+    data?: Record<string, string | number>;
+    /**
+     * Set when the finding comes from inside a contained file: the file's name, with " > " between nesting levels.
+     * `location` then starts with where that file sits.
+     */
+    attachment?: string;
+    /** How much the finding adds to a score, set by the package that made it. */
+    weight?: number;
+}
+/** A finding office-defuse makes itself. */
+export interface OfficeFinding extends DefuseFinding {
+    category: OfficeCategory;
+    detail: OfficeDetail;
+}
+export declare enum OfficeRisk {
+    None = "NONE",
+    Low = "LOW",
+    Medium = "MEDIUM",
+    High = "HIGH",
+    Critical = "CRITICAL",
+    /** The file could not be inspected: a refusal of the container or XML layer, or a limit, stopped the run. */
+    Unknown = "UNKNOWN"
+}
+export interface OfficeInspection {
+    status: 'clean' | 'strippable' | 'rejected';
+    /** 0 to 100, null when risk is UNKNOWN. */
+    score: number | null;
+    risk: OfficeRisk;
+    findings: DefuseFinding[];
+    /** The format the content says, as its usual file extension without the dot, such as 'docx' or 'ods'. '' when not recognized. */
+    format: string;
+    /** The MIME type of a file in that format. '' when not recognized. */
+    mimeType: string;
+}
+/** Random-access input. A buffer, a local file and an S3 ranged GetObject all fit. */
+export interface ByteSource {
+    size(): Promise<number>;
+    read(offset: number, length: number): Promise<Uint8Array>;
+    close?(): Promise<void>;
+}
+/** Append-only output. Never seeks. */
+export interface ByteSink {
+    write(chunk: Uint8Array): Promise<void>;
+    close(): Promise<void>;
+    /** Called instead of close() when copying to the sink fails, so a partial output is not taken for a whole one. */
+    abort?(error: unknown): Promise<void>;
+}
+export interface OfficeLimits {
+    /** Bytes in the upload. Not enforced unless set. */
+    fileSize?: number;
+    /** Entries in the ZIP central directory. Default 10,000. */
+    entries?: number;
+    /** Declared decompressed size of any one entry, in bytes. Default 512 MiB. */
+    decompressedBytes?: number;
+    /** Declared decompressed sizes of all entries together, in bytes. Default 2 GiB. */
+    totalDecompressedBytes?: number;
+    /** Element nesting depth in one XML part. Default 256. */
+    xmlDepth?: number;
+    /** Characters in one XML tag, comment, processing instruction or CDATA section. Default 16 Mi. */
+    xmlTokenSize?: number;
+    /** Entity references nested inside entity text. Default 16. */
+    xmlEntityDepth?: number;
+    /** Entity references expanded in the whole run. Default 100,000. */
+    xmlEntityExpansions?: number;
+    /** Characters of entity text expanded in the whole run. Default 16 Mi. */
+    xmlEntitySize?: number;
+    /** Milliseconds for the whole run. Not enforced unless set. */
+    timeMs?: number;
+}
+/** What a contained file plugin learns of the run, with nothing format-specific, so any package of the family can make one. */
+export interface PluginContext {
+    /** The depth of the file itself: 0 for the upload, 1 for a file inside it, and so on, whatever the formats. */
+    depth: number;
+    /** When a time limit is set, the Date.now() value the whole run must finish by. Nested runs share it. */
+    deadline?: number;
+}
+export interface ContainedFile {
+    name?: string;
+    /** The MIME type the container declares for the file, such as a part's content type. */
+    declaredType?: string;
+    /** From the first bytes. */
+    sniffedType?: string;
+    /** Decoded size. */
+    size: number;
+    location: string;
+    /** The depth of the file itself: 0 for the upload, 1 for a file inside it, and so on, whatever the formats. */
+    depth: number;
+    /** Decoded bytes. */
+    source: ByteSource;
+}
+/** What a file plugin did, plus anything it found inside the file. */
+export interface ContainedFileResult {
+    result: 'scrubbed' | 'passed' | 'removed';
+    /** Findings inside the file as it arrived. They go into the report of the file that contains it. */
+    findings?: DefuseFinding[];
+    /** Findings inside the bytes the plugin kept. They go into the report of the output. */
+    outputFindings?: DefuseFinding[];
+}
+export interface ContainedFilePlugin {
+    kind: 'file';
+    name: string;
+    accepts(file: ContainedFile): boolean | Promise<boolean>;
+    /** Writes the bytes to keep. Returning 'removed' drops the file after all. */
+    process(file: ContainedFile, sink: ByteSink, context: PluginContext): Promise<'scrubbed' | 'passed' | 'removed' | ContainedFileResult>;
+}
+export interface OfficeActionOverride {
+    category: OfficeCategory;
+    detail?: OfficeDetail;
+    action: OfficeFindingAction;
+}
+export interface OfficeScoreWeight {
+    category: OfficeCategory;
+    detail?: OfficeDetail;
+    weight: number;
+}
+/** Lower bound of each band. */
+export interface OfficeScoreBands {
+    low: number;
+    medium: number;
+    high: number;
+    critical: number;
+}
+export interface OfficeOptions {
+    limits?: OfficeLimits;
+    actionOverrides?: OfficeActionOverride[];
+    scoreWeights?: OfficeScoreWeight[];
+    scoreBands?: OfficeScoreBands;
+}

package/dist/types.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OfficeRisk = exports.OfficeDetail = exports.OfficeCategory = void 0;
+/** High-level kind of a finding. */
+var OfficeCategory;
+(function (OfficeCategory) {
+    OfficeCategory["Container"] = "CONTAINER";
+    OfficeCategory["Xml"] = "XML";
+    OfficeCategory["Limit"] = "LIMIT";
+    OfficeCategory["Package"] = "PACKAGE";
+    OfficeCategory["Encrypted"] = "ENCRYPTED";
+    OfficeCategory["Macro"] = "MACRO";
+    OfficeCategory["Ui"] = "UI";
+    OfficeCategory["Action"] = "ACTION";
+    OfficeCategory["Dde"] = "DDE";
+    OfficeCategory["Field"] = "FIELD";
+    OfficeCategory["External"] = "EXTERNAL";
+    OfficeCategory["Link"] = "LINK";
+    OfficeCategory["Embedded"] = "EMBEDDED";
+    OfficeCategory["Control"] = "CONTROL";
+})(OfficeCategory || (exports.OfficeCategory = OfficeCategory = {}));
+/** Exact variant of a finding. Some details appear under more than one category. */
+var OfficeDetail;
+(function (OfficeDetail) {
+    // CONTAINER
+    OfficeDetail["NotZip"] = "NOT_ZIP";
+    OfficeDetail["AmbiguousEnd"] = "AMBIGUOUS_END";
+    OfficeDetail["MultiDisk"] = "MULTI_DISK";
+    OfficeDetail["DirectoryMismatch"] = "DIRECTORY_MISMATCH";
+    OfficeDetail["OutOfRange"] = "OUT_OF_RANGE";
+    OfficeDetail["Overlap"] = "OVERLAP";
+    OfficeDetail["HeaderMismatch"] = "HEADER_MISMATCH";
+    OfficeDetail["DuplicateName"] = "DUPLICATE_NAME";
+    OfficeDetail["UnsafeName"] = "UNSAFE_NAME";
+    OfficeDetail["NameEncoding"] = "NAME_ENCODING";
+    OfficeDetail["EncryptedEntry"] = "ENCRYPTED_ENTRY";
+    OfficeDetail["UnsupportedMethod"] = "UNSUPPORTED_METHOD";
+    OfficeDetail["Zip64Mismatch"] = "ZIP64_MISMATCH";
+    OfficeDetail["BadExtraField"] = "BAD_EXTRA_FIELD";
+    OfficeDetail["DataError"] = "DATA_ERROR";
+    OfficeDetail["LeadingBytes"] = "LEADING_BYTES";
+    OfficeDetail["HiddenData"] = "HIDDEN_DATA";
+    OfficeDetail["TrailingBytes"] = "TRAILING_BYTES";
+    // XML
+    OfficeDetail["Doctype"] = "DOCTYPE";
+    OfficeDetail["InternalSubset"] = "INTERNAL_SUBSET";
+    OfficeDetail["ExternalEntity"] = "EXTERNAL_ENTITY";
+    OfficeDetail["Malformed"] = "MALFORMED";
+    OfficeDetail["Encoding"] = "ENCODING";
+    // LIMIT
+    OfficeDetail["FileSize"] = "FILE_SIZE";
+    OfficeDetail["EntryCount"] = "ENTRY_COUNT";
+    OfficeDetail["DecompressedSize"] = "DECOMPRESSED_SIZE";
+    OfficeDetail["TotalDecompressedSize"] = "TOTAL_DECOMPRESSED_SIZE";
+    OfficeDetail["XmlDepth"] = "XML_DEPTH";
+    OfficeDetail["XmlTokenSize"] = "XML_TOKEN_SIZE";
+    OfficeDetail["XmlEntityDepth"] = "XML_ENTITY_DEPTH";
+    OfficeDetail["XmlEntityExpansions"] = "XML_ENTITY_EXPANSIONS";
+    OfficeDetail["XmlEntitySize"] = "XML_ENTITY_SIZE";
+    OfficeDetail["Time"] = "TIME";
+    // PACKAGE
+    OfficeDetail["Unrecognized"] = "UNRECOGNIZED";
+    OfficeDetail["AmbiguousFormat"] = "AMBIGUOUS_FORMAT";
+    OfficeDetail["Unreadable"] = "UNREADABLE";
+    OfficeDetail["DuplicateEntry"] = "DUPLICATE_ENTRY";
+    OfficeDetail["UntypedPart"] = "UNTYPED_PART";
+    OfficeDetail["UnreferencedPart"] = "UNREFERENCED_PART";
+    OfficeDetail["OdfLayout"] = "ODF_LAYOUT";
+    // ENCRYPTED
+    OfficeDetail["PasswordRequired"] = "PASSWORD_REQUIRED";
+    // MACRO
+    OfficeDetail["VbaProject"] = "VBA_PROJECT";
+    OfficeDetail["XlmMacrosheet"] = "XLM_MACROSHEET";
+    OfficeDetail["OdfBasic"] = "ODF_BASIC";
+    OfficeDetail["OdfScripts"] = "ODF_SCRIPTS";
+    OfficeDetail["OdfDialogs"] = "ODF_DIALOGS";
+    OfficeDetail["EventOnOpen"] = "EVENT_ON_OPEN";
+    OfficeDetail["Event"] = "EVENT";
+    OfficeDetail["Link"] = "LINK";
+    // UI
+    OfficeDetail["Ribbon"] = "RIBBON";
+    OfficeDetail["Callback"] = "CALLBACK";
+    OfficeDetail["OdfConfiguration"] = "ODF_CONFIGURATION";
+    // ACTION
+    OfficeDetail["RunProgram"] = "RUN_PROGRAM";
+    OfficeDetail["OleVerb"] = "OLE_VERB";
+    // DDE
+    OfficeDetail["Field"] = "FIELD";
+    OfficeDetail["Formula"] = "FORMULA";
+    // FIELD
+    OfficeDetail["Macrobutton"] = "MACROBUTTON";
+    OfficeDetail["Computed"] = "COMPUTED";
+    // EXTERNAL
+    OfficeDetail["Template"] = "TEMPLATE";
+    OfficeDetail["Object"] = "OBJECT";
+    OfficeDetail["Image"] = "IMAGE";
+    OfficeDetail["Frame"] = "FRAME";
+    OfficeDetail["Include"] = "INCLUDE";
+    OfficeDetail["Workbook"] = "WORKBOOK";
+    OfficeDetail["Reload"] = "RELOAD";
+    OfficeDetail["Other"] = "OTHER";
+    OfficeDetail["LocalFile"] = "LOCAL_FILE";
+    // LINK
+    OfficeDetail["Safe"] = "SAFE";
+    OfficeDetail["FileUrl"] = "FILE_URL";
+    OfficeDetail["NetworkPath"] = "NETWORK_PATH";
+    OfficeDetail["DataUrl"] = "DATA_URL";
+    OfficeDetail["ScriptUrl"] = "SCRIPT_URL";
+    OfficeDetail["OtherScheme"] = "OTHER_SCHEME";
+    OfficeDetail["Credentials"] = "CREDENTIALS";
+    OfficeDetail["IpHost"] = "IP_HOST";
+    OfficeDetail["LookalikeHost"] = "LOOKALIKE_HOST";
+    OfficeDetail["EncodedHost"] = "ENCODED_HOST";
+    OfficeDetail["Relative"] = "RELATIVE";
+    // EMBEDDED
+    OfficeDetail["OleObject"] = "OLE_OBJECT";
+    OfficeDetail["Package"] = "PACKAGE";
+    OfficeDetail["OleFile"] = "OLE_FILE";
+    OfficeDetail["Applet"] = "APPLET";
+    OfficeDetail["Plugin"] = "PLUGIN";
+    // CONTROL
+    OfficeDetail["ActiveX"] = "ACTIVEX";
+})(OfficeDetail || (exports.OfficeDetail = OfficeDetail = {}));
+var OfficeRisk;
+(function (OfficeRisk) {
+    OfficeRisk["None"] = "NONE";
+    OfficeRisk["Low"] = "LOW";
+    OfficeRisk["Medium"] = "MEDIUM";
+    OfficeRisk["High"] = "HIGH";
+    OfficeRisk["Critical"] = "CRITICAL";
+    /** The file could not be inspected: a refusal of the container or XML layer, or a limit, stopped the run. */
+    OfficeRisk["Unknown"] = "UNKNOWN";
+})(OfficeRisk || (exports.OfficeRisk = OfficeRisk = {}));

package/dist/xlsb.d.ts

@@ -0,0 +1,19 @@
+export interface DdeLink {
+    application: string;
+    topic: string;
+}
+/**
+ * Reads the records of an .xlsb external link part as its chunks arrive, and collects its DDE links. Each record
+ * body is skipped, except the first 64 KiB of a BrtBeginSupBook. A header that breaks the record format ends the
+ * reading; Excel cannot read such a part either.
+ */
+export declare class XlsbLinks {
+    readonly dde: DdeLink[];
+    private head;
+    private left;
+    private body;
+    private kept;
+    private broken;
+    write(chunk: Uint8Array): void;
+    private finish;
+}

package/dist/xlsb.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.XlsbLinks = void 0;
+/** BrtBeginSupBook, the record that opens each link of an .xlsb external link part. */
+const BEGIN_SUPBOOK = 360;
+/** The link type BrtBeginSupBook gives a DDE link. */
+const SUPBOOK_DDE = 1;
+/** How much of one BrtBeginSupBook is kept: far more than the two names of a DDE link need. */
+const KEEP = 65536;
+/**
+ * The record header at the start of `b`: the record's type and size, undefined while `b` is too short, or 'bad' when
+ * the header runs longer than the format allows. A type takes one or two bytes and a size one to four, seven bits to
+ * a byte, and a byte with its high bit clear ends each.
+ */
+function header(b) {
+    let i = 0;
+    let type = 0;
+    for (let shift = 0;; shift += 7) {
+        if (i >= b.length)
+            return undefined;
+        type |= (b[i] & 0x7f) << shift;
+        if (!(b[i++] & 0x80))
+            break;
+        if (shift === 7)
+            return 'bad';
+    }
+    let size = 0;
+    for (let shift = 0;; shift += 7) {
+        if (i >= b.length)
+            return undefined;
+        size += (b[i] & 0x7f) * 2 ** shift;
+        if (!(b[i++] & 0x80))
+            break;
+        if (shift === 21)
+            return 'bad';
+    }
+    return { type, size };
+}
+/** An XLWideString at `at`: a 32-bit character count, then UTF-16LE. Cut short at the end of what was kept. */
+function wideString(b, at) {
+    if (at + 4 > b.length)
+        return { text: '', next: b.length };
+    const end = Math.min(b.length, at + 4 + b.readUInt32LE(at) * 2);
+    return { text: b.toString('utf16le', at + 4, end), next: end };
+}
+/**
+ * Reads the records of an .xlsb external link part as its chunks arrive, and collects its DDE links. Each record
+ * body is skipped, except the first 64 KiB of a BrtBeginSupBook. A header that breaks the record format ends the
+ * reading; Excel cannot read such a part either.
+ */
+class XlsbLinks {
+    dde = [];
+    head = [];
+    left = 0;
+    body;
+    kept = 0;
+    broken = false;
+    write(chunk) {
+        let i = 0;
+        while (i < chunk.length && !this.broken) {
+            if (this.left > 0) {
+                const n = Math.min(this.left, chunk.length - i);
+                if (this.body && this.kept < KEEP) {
+                    const part = Buffer.from(chunk.subarray(i, i + Math.min(n, KEEP - this.kept)));
+                    this.body.push(part);
+                    this.kept += part.length;
+                }
+                this.left -= n;
+                i += n;
+                if (this.left === 0)
+                    this.finish();
+                continue;
+            }
+            this.head.push(chunk[i++]);
+            const h = header(this.head);
+            if (h === undefined)
+                continue;
+            if (h === 'bad') {
+                this.broken = true;
+                return;
+            }
+            this.head = [];
+            this.body = h.type === BEGIN_SUPBOOK ? [] : undefined;
+            this.kept = 0;
+            this.left = h.size;
+            if (this.left === 0)
+                this.finish();
+        }
+    }
+    finish() {
+        if (!this.body)
+            return;
+        const b = Buffer.concat(this.body);
+        this.body = undefined;
+        if (b.length < 2 || b.readUInt16LE(0) !== SUPBOOK_DDE)
+            return;
+        const application = wideString(b, 2);
+        this.dde.push({ application: application.text, topic: wideString(b, application.next).text });
+    }
+}
+exports.XlsbLinks = XlsbLinks;