@patrickdk77/office-defuse 0.2.0 → 0.2.2

package/dist/types.d.ts

@@ -234,6 +234,29 @@ export interface OfficeLimits {
     /** Milliseconds for the whole run. Not enforced unless set. */
     timeMs?: number;
 }
+export interface FormatDetection {
+    /** The format's MIME type, such as application/vnd.openxmlformats-officedocument.wordprocessingml.document. */
+    mimeType: string;
+    /** The format's usual extension, lowercase and without the dot. */
+    extension: string;
+    /** Where the format starts in the file: 0, or the offset of its data when other data comes first. */
+    offset: number;
+    /** Set when the match rests on more than the content, and says what it rests on. */
+    heuristic?: string;
+}
+/** What a detect function may know of a file besides its content. */
+export interface DetectOptions {
+    /** The file's name, as the upload or the container that holds it gives it. */
+    name?: string;
+    /** The MIME type the upload or the container declares. */
+    declaredType?: string;
+    /** The Date.now() value detection must finish by, as `PluginContext.deadline`. */
+    deadline?: number;
+    /** Folder for temporary files. Defaults to `os.tmpdir()`. */
+    tempDir?: string;
+    /** Bytes held in memory before a temporary file takes over. */
+    memoryThreshold?: 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. */

package/dist/word.d.ts

@@ -1,9 +1,9 @@
 import type { CfbEntry, CompoundFile } from './cfb';
 import type { RunContext } from './context';
+/** Whether a WordDocument stream holds a template: its FIB has fDot set. */
+export declare function isWordTemplate(cfb: CompoundFile, stream: CfbEntry): Promise<boolean>;
 /**
  * Inspects a Word 6.0 to 2003 document: its FIB, whether it is encrypted, the fields in its text and the template it
- * attaches. Returns whether it is a template, or undefined for an `optional` stream that holds no FIB.
+ * attaches. An `optional` stream that holds no FIB is not read.
  */
-export declare function wordRules(ctx: RunContext, cfb: CompoundFile, stream: CfbEntry, optional?: boolean): Promise<{
-    template: boolean;
-} | undefined>;
+export declare function wordRules(ctx: RunContext, cfb: CompoundFile, stream: CfbEntry, optional?: boolean): Promise<void>;

package/dist/word.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWordTemplate = isWordTemplate;
 exports.wordRules = wordRules;
 const errors_1 = require("./errors");
 const fields_1 = require("./fields");
@@ -26,20 +27,33 @@ const decrypted = (src, decrypt) => ({
     read: async (offset, length) => decrypt(offset, await src.read(offset, length)),
 });
 const u32 = (b, at) => (b[at] | (b[at + 1] << 8) | (b[at + 2] << 16) | (b[at + 3] << 24)) >>> 0;
+/**
+ * The identifier and flags of the FIB a WordDocument stream starts with (MS-DOC 2.5.2), or undefined when it does not
+ * start with the FIB of Word 6.0 to 2003. The FIB's base is never encrypted.
+ */
+function fibBase(fib) {
+    const ident = fib.length >= 32 ? u16(fib, 0) : 0;
+    return ident === WORD8 || ident === WORD6 ? { ident, flags: u16(fib, 10) } : undefined;
+}
+/** Whether a WordDocument stream holds a template: its FIB has fDot set. */
+async function isWordTemplate(cfb, stream) {
+    const base = fibBase(await cfb.source(stream).read(0, 32));
+    return base !== undefined && (base.flags & 1) === 1;
+}
 /**
  * Inspects a Word 6.0 to 2003 document: its FIB, whether it is encrypted, the fields in its text and the template it
- * attaches. Returns whether it is a template, or undefined for an `optional` stream that holds no FIB.
+ * attaches. An `optional` stream that holds no FIB is not read.
  */
 async function wordRules(ctx, cfb, stream, optional = false) {
     let source = cfb.source(stream);
     let fib = await source.read(0, 1024);
-    const ident = fib.length >= 32 ? u16(fib, 0) : 0;
-    if (ident !== WORD8 && ident !== WORD6) {
+    const base = fibBase(fib);
+    if (!base) {
         if (optional)
-            return undefined;
+            return;
         throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, 'The WordDocument stream does not start with a Word FIB', { reason: 'a WordDocument stream without a FIB' });
     }
-    const flags = u16(fib, 10);
+    const { ident, flags } = base;
     const tableEntry = cfb.child(cfb.root, flags & 0x0200 ? '1Table' : '0Table');
     let tableSource = tableEntry?.kind === 'stream' ? cfb.source(tableEntry) : undefined;
     // fEncrypted, set for RC4, RC4 CryptoAPI and XOR obfuscation alike. Word 97 to 2003 documents are read through the
@@ -126,7 +140,6 @@ async function wordRules(ctx, cfb, stream, optional = false) {
         }
     }
     fields.finish();
-    return { template: (flags & 1) === 1 };
 }
 /** The fc and lcb pairs of a Word 97 FIB, after its variable-length arrays of 16- and 32-bit values. */
 function fcLcb(fib) {

package/dist/xls.d.ts

@@ -8,16 +8,22 @@ export type Decrypt = (r: BiffRecord) => Uint8Array;
  * reads workbooks without knowing how they are encrypted.
  */
 export type Unlock = (ctx: RunContext, filePass: BiffRecord, stream: string) => Decrypt | Promise<Decrypt>;
+/**
+ * Whether a workbook stream holds a template or an add-in: its globals substream, from the BOF that starts the stream
+ * to its EOF, holds a Template or an AddIn record. Record headers are never encrypted, so an encrypted workbook tells
+ * this without its password. A stream that does not start with a BOF record is neither.
+ */
+export declare function workbookKind(cfb: CompoundFile, stream: CfbEntry, deadline?: number): Promise<{
+    template: boolean;
+    addIn: boolean;
+}>;
 /**
  * Inspects an Excel 5.0 to 2003 workbook stream. Excel reads the globals substream from the start of the stream,
  * then each sheet from where its BoundSheet record says the sheet starts. The globals give the macro sheets, the
  * names Excel runs as macros, and the DDE, OLE and workbook links. The sheets give shapes that run macros and
  * hyperlinks. An encrypted workbook goes through `unlock`.
  */
-export declare function excelRules(ctx: RunContext, cfb: CompoundFile, stream: CfbEntry, unlock: Unlock): Promise<{
-    template: boolean;
-    addIn: boolean;
-}>;
+export declare function excelRules(ctx: RunContext, cfb: CompoundFile, stream: CfbEntry, unlock: Unlock): Promise<void>;
 /**
  * A VirtualPath (MS-XLS 2.5.277) written out. One that starts with U+0001 is encoded: its control characters name a
  * volume, the root, a folder, a step up, a URL's volume or Excel's startup folders.

package/dist/xls.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.workbookKind = workbookKind;
 exports.excelRules = excelRules;
 exports.virtualPath = virtualPath;
 exports.hyperlink = hyperlink;
@@ -21,6 +22,25 @@ const FORMULA_AT = new Map([
     [SHRFMLA, 8],
     [ARRAY, 12],
 ]);
+/**
+ * Whether a workbook stream holds a template or an add-in: its globals substream, from the BOF that starts the stream
+ * to its EOF, holds a Template or an AddIn record. Record headers are never encrypted, so an encrypted workbook tells
+ * this without its password. A stream that does not start with a BOF record is neither.
+ */
+async function workbookKind(cfb, stream, deadline) {
+    const kind = { template: false, addIn: false };
+    const records = new biff_1.RecordReader(cfb, stream, 0, deadline);
+    const first = await records.next();
+    if (first?.type !== biff_1.R.bof || first.body.length < 4)
+        return kind;
+    for (let r = await records.next(); r && r.type !== biff_1.R.eof; r = await records.next()) {
+        if (r.type === biff_1.R.template)
+            kind.template = true;
+        else if (r.type === biff_1.R.addIn)
+            kind.addIn = true;
+    }
+    return kind;
+}
 /**
  * Inspects an Excel 5.0 to 2003 workbook stream. Excel reads the globals substream from the start of the stream,
  * then each sheet from where its BoundSheet record says the sheet starts. The globals give the macro sheets, the
@@ -40,7 +60,6 @@ async function excelRules(ctx, cfb, stream, unlock) {
     const names = [];
     /** The SupBook each XTI of the ExternSheet record names. */
     const xti = [];
-    const flags = { template: false, addIn: false };
     for (let r = await records.next(); r && r.type !== biff_1.R.eof; r = await records.next()) {
         if (r.type === biff_1.R.filePass) {
             decrypt = await unlock(ctx, r, location);
@@ -49,10 +68,6 @@ async function excelRules(ctx, cfb, stream, unlock) {
         const body = decrypt(r);
         if (r.type === biff_1.R.boundSheet)
             sheets.push((0, biff_1.parseBoundSheet)(body, biff8));
-        else if (r.type === biff_1.R.template)
-            flags.template = true;
-        else if (r.type === biff_1.R.addIn)
-            flags.addIn = true;
         else if (r.type === biff_1.R.lbl) {
             const name = (0, biff_1.parseLbl)(body, biff8);
             names.push(name.name);
@@ -85,7 +100,6 @@ async function excelRules(ctx, cfb, stream, unlock) {
     const nameOf = (ref) => (ref.kind === 'name' ? names[ref.index - 1] : books[xti[ref.ixti] ?? -1]?.names[ref.index - 1]);
     for (const s of sheets)
         await sheetRules(ctx, cfb, stream, s, decrypt, location, biff8 ? nameOf : undefined);
-    return flags;
 }
 /** A SupBook record, read as MS-XLS 2.4.271 and oletools tell its kinds apart. */
 function linkRules(ctx, b, location) {

package/dist/xml.d.ts

@@ -159,6 +159,9 @@ export declare class XmlTokenizer {
     /** The XML declaration says standalone="yes". */
     private standalone;
     private encoding;
+    /** Set by a declaration of US-ASCII, which agrees with UTF-8 only while every byte is ASCII. */
+    private asciiDeclared;
+    private nonAscii;
     /** Start tags read so far, which numbers the elements. */
     private elements;
     /** An attribute value of the tag being read referred to an entity of the internal subset. */

package/dist/xml.js

@@ -190,6 +190,9 @@ class XmlTokenizer {
     /** The XML declaration says standalone="yes". */
     standalone = false;
     encoding = 'utf-8';
+    /** Set by a declaration of US-ASCII, which agrees with UTF-8 only while every byte is ASCII. */
+    asciiDeclared = false;
+    nonAscii = false;
     /** Start tags read so far, which numbers the elements. */
     elements = 0;
     /** An attribute value of the tag being read referred to an entity of the internal subset. */
@@ -263,6 +266,14 @@ class XmlTokenizer {
         return decoder;
     }
     decode(decoder, bytes, more) {
+        if (!this.nonAscii)
+            for (const c of bytes)
+                if (c >= 0x80) {
+                    this.nonAscii = true;
+                    break;
+                }
+        if (this.asciiDeclared && this.nonAscii)
+            this.stop(types_1.OfficeDetail.Encoding, 'The declaration says us-ascii, the bytes are not all ASCII');
         try {
             return decoder.decode(bytes, { stream: more });
         }
@@ -279,9 +290,16 @@ class XmlTokenizer {
         const declared = /\bencoding\s*=\s*(["'])([^"']*)\1/.exec(body)?.[2]?.toLowerCase();
         if (declared === undefined)
             return;
-        const ok = this.encoding === 'utf-8' ? declared === 'utf-8' || declared === 'utf8' : declared === 'utf-16' || declared === this.encoding;
+        // SharePoint declares us-ascii on the custom XML it writes. ASCII bytes read the same in UTF-8.
+        const ascii = this.encoding === 'utf-8' && (declared === 'us-ascii' || declared === 'ascii');
+        const ok = this.encoding === 'utf-8' ? declared === 'utf-8' || declared === 'utf8' || ascii : declared === 'utf-16' || declared === this.encoding;
         if (!ok)
             this.stop(types_1.OfficeDetail.Encoding, `The declaration says ${declared}, the bytes are ${this.encoding.toUpperCase()}`);
+        if (ascii) {
+            this.asciiDeclared = true;
+            if (this.nonAscii)
+                this.stop(types_1.OfficeDetail.Encoding, 'The declaration says us-ascii, the bytes are not all ASCII');
+        }
     }
     feed(text, final) {
         this.buf = this.pos < this.buf.length ? this.buf.slice(this.pos) + text : text;

package/dist/zip.d.ts

@@ -48,6 +48,8 @@ export declare class ZipArchive {
     readonly entries: ZipEntry[];
     readonly notes: ZipNote[];
     private readonly deadline;
+    /** Where the archive's data starts: the first local header, or the central directory of an archive without entries. */
+    readonly start: number;
     private readonly byKey;
     private constructor();
     /** The entry with this name, compared as entry names collide: ignoring case. */

package/dist/zip.js

@@ -241,12 +241,16 @@ class ZipArchive {
     entries;
     notes;
     deadline;
+    start;
     byKey = new Map();
-    constructor(reader, entries, notes, deadline) {
+    constructor(reader, entries, notes, deadline, 
+    /** Where the archive's data starts: the first local header, or the central directory of an archive without entries. */
+    start) {
         this.reader = reader;
         this.entries = entries;
         this.notes = notes;
         this.deadline = deadline;
+        this.start = start;
         for (const e of entries)
             this.byKey.set(nameKey(e.name), e);
     }
@@ -447,7 +451,7 @@ class ZipArchive {
             if (at !== undefined)
                 notes.push({ detail: types_1.OfficeDetail.HiddenEntry, bytes: to - from, offset: at });
         }
-        return new ZipArchive(reader, entries, notes, deadline);
+        return new ZipArchive(reader, entries, notes, deadline, sorted.length ? sorted[0].localOffset : dirOffset);
     }
     /** Checks a local header and any data descriptor against the central directory, and fills in where the entry's data and the entry end. */
     static async checkLocal(reader, e, rawName, dirOffset) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patrickdk77/office-defuse",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Inspect Office and OpenDocument files for VBA and Excel 4.0 macros, LibreOffice Basic and scripts, DDE, external templates and links, embedded OLE objects and ActiveX controls, and score the risk. Strict ZIP and XML readers, bounded memory, no runtime dependencies.",
   "license": "MIT",
   "author": "patrickdk77",