@patrickdk77/office-defuse 0.1.0 → 0.2.0

package/dist/word.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.wordRules = wordRules;
+const errors_1 = require("./errors");
+const fields_1 = require("./fields");
+const io_1 = require("./io");
+const offcrypto_1 = require("./offcrypto");
+const oleobj_1 = require("./oleobj");
+const types_1 = require("./types");
+/** wIdent of Word 97 and later, and of Word 6.0 and 95 (MS-DOC 2.5.2). */
+const WORD8 = 0xa5ec;
+const WORD6 = 0xa5dc;
+/** FibRgFcLcb97 pairs (MS-DOC 2.5.6): the attached template's table and the piece table. */
+const FC_STTBF_ASSOC = 32;
+const FC_CLX = 33;
+/** In a Word 6.0 or 95 FIB, the length of the macro table that holds WordBasic macros. Word writes 2 for an empty one. */
+const WORD6_MACROS = 0x11c;
+/** In a Word 6.0 or 95 FIB, fcClx and lcbClx: where the piece table of a file saved fast lies in the WordDocument stream. */
+const WORD6_CLX = 0x160;
+/** Text is read in pieces of at most this many characters. */
+const PIECE = 65536;
+const u16 = (b, at) => b[at] | (b[at + 1] << 8);
+/** A stream read through its decryption. */
+const decrypted = (src, decrypt) => ({
+    size: () => src.size(),
+    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;
+/**
+ * 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.
+ */
+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) {
+        if (optional)
+            return undefined;
+        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 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
+    // decryption. A Word 6.0 or 95 document's encryption is another, which this reader does not undo.
+    if (flags & 0x0100) {
+        if (ident === WORD6 || !tableSource)
+            throw new errors_1.StopError(types_1.OfficeCategory.Encrypted, types_1.OfficeDetail.PasswordRequired, 'The document is encrypted', { stream: stream.name });
+        const key = await (0, offcrypto_1.unlockDocument)(ctx, fib, tableSource, stream.name);
+        source = decrypted(source, key.word);
+        tableSource = decrypted(tableSource, key.table);
+        fib = await source.read(0, 1024);
+    }
+    const location = stream.name;
+    const fields = new fields_1.FieldStack(ctx, location);
+    // Word marks a field's start, separator and end with 0x13, 0x14 and 0x15 in the text. Other control characters in
+    // a field's code, such as the 0x01 of a hyperlink's data, are not part of what it says.
+    const text = (s) => {
+        for (const ch of s) {
+            if (ch === '\x13')
+                fields.begin();
+            else if (ch === '\x14')
+                fields.separate();
+            else if (ch === '\x15')
+                fields.end();
+            else if (ch >= ' ' || ch === '\t') {
+                if (fields.inCode)
+                    fields.text(ch);
+                else
+                    fields.result(ch);
+            }
+        }
+    };
+    const reader = new io_1.Reader(source, stream.size, 65536, 8);
+    if (ident === WORD6) {
+        // Word 6.0 and 95 keep their text as 8-bit characters. A file saved fast (fComplex) adds pieces to the end, and its
+        // piece table, in the WordDocument stream itself at fcClx (FIB offset 0x160), gives their order. Any other file,
+        // or one whose piece table does not read, is read from fcMin to fcMac, every byte between, as msodde does.
+        const clxAt = u32(fib, WORD6_CLX);
+        const clxSize = u32(fib, WORD6_CLX + 4);
+        const list = flags & 0x0004 && clxSize > 0 && clxAt + clxSize <= stream.size ? pieces(await reader.read(clxAt, clxSize)).filter(p => !p.compressed && p.fc + p.length <= stream.size) : [];
+        if (list.length) {
+            for (const p of list) {
+                for (let cp = 0; cp < p.length; cp += PIECE) {
+                    (0, errors_1.checkTime)(ctx.settings.deadline);
+                    text(latin(await reader.read(p.fc + cp, Math.min(PIECE, p.length - cp))));
+                }
+            }
+        }
+        else {
+            const from = u32(fib, 0x18);
+            const to = Math.min(u32(fib, 0x1c), stream.size);
+            for (let at = from; at < to; at += PIECE) {
+                (0, errors_1.checkTime)(ctx.settings.deadline);
+                text(latin(await reader.read(at, Math.min(PIECE, to - at))));
+            }
+        }
+        if (fib.length >= WORD6_MACROS + 4 && u32(fib, WORD6_MACROS) > 2)
+            ctx.report(types_1.OfficeCategory.Macro, types_1.OfficeDetail.WordBasic, location, { stream: location, bytes: u32(fib, WORD6_MACROS) });
+    }
+    else {
+        const pairs = fcLcb(fib);
+        const table = tableEntry;
+        if (table?.kind === 'stream' && tableSource) {
+            const clx = pairs[FC_CLX];
+            if (clx && clx.lcb > 0 && clx.fc + clx.lcb <= table.size) {
+                for (const p of pieces(await tableSource.read(clx.fc, clx.lcb))) {
+                    for (let cp = 0; cp < p.length; cp += PIECE) {
+                        (0, errors_1.checkTime)(ctx.settings.deadline);
+                        const n = Math.min(PIECE, p.length - cp);
+                        if (p.compressed)
+                            text(latin(await reader.read(p.fc + cp, n)));
+                        else
+                            text((0, oleobj_1.utf16)(await reader.read(p.fc + cp * 2, n * 2)));
+                    }
+                }
+            }
+            const assoc = pairs[FC_STTBF_ASSOC];
+            if (assoc && assoc.lcb > 0 && assoc.fc + assoc.lcb <= table.size) {
+                // The attached template is string 1 of SttbfAssoc (MS-DOC 2.9.271).
+                const template = sttb(await tableSource.read(assoc.fc, Math.min(assoc.lcb, 65536)))[1] ?? '';
+                if (template.trim())
+                    ctx.external(types_1.OfficeDetail.Template, template, location, { source: 'SttbfAssoc' }, 'template');
+            }
+        }
+    }
+    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) {
+    const r = new oleobj_1.ByteReader(fib);
+    const out = [];
+    return (0, oleobj_1.bounded)(() => {
+        r.skip(32);
+        r.skip(r.u16() * 2);
+        r.skip(r.u16() * 4);
+        const n = r.u16();
+        for (let i = 0; i < n; i++)
+            out.push({ fc: r.u32(), lcb: r.u32() });
+        return out;
+    }, () => out);
+}
+/** The pieces of a Clx (MS-DOC 2.9.38): where each run of text is, and whether it is stored 8 bits a character. */
+function pieces(clx) {
+    const r = new oleobj_1.ByteReader(clx);
+    const out = [];
+    return (0, oleobj_1.bounded)(() => {
+        // Prc entries of formatting come first, each with its size.
+        while (r.left > 0 && clx[r.pos] === 0x01) {
+            r.skip(1);
+            r.skip(r.u16());
+        }
+        if (r.u8() !== 0x02)
+            return out;
+        const lcb = r.u32();
+        const n = Math.floor((lcb - 4) / 12);
+        const plc = new oleobj_1.ByteReader(r.bytes(Math.min(lcb, r.left)));
+        const cps = [];
+        for (let i = 0; i <= n; i++)
+            cps.push(plc.u32());
+        for (let i = 0; i < n; i++) {
+            plc.skip(2);
+            const fc = plc.u32();
+            plc.skip(2);
+            const length = cps[i + 1] - cps[i];
+            if (length <= 0)
+                continue;
+            const compressed = (fc & 0x40000000) !== 0;
+            out.push({ fc: compressed ? (fc & 0x3fffffff) / 2 : fc, length, compressed });
+        }
+        return out;
+    }, () => []);
+}
+/** The strings of an STTB (MS-DOC 2.2.4), in 16-bit characters when it starts with 0xFFFF, as Word 97 writes one. */
+function sttb(b) {
+    const r = new oleobj_1.ByteReader(b);
+    const out = [];
+    return (0, oleobj_1.bounded)(() => {
+        const wide = r.u16() === 0xffff;
+        if (!wide)
+            r.pos = 0;
+        const count = r.u16();
+        const extra = r.u16();
+        for (let i = 0; i < count; i++) {
+            const n = wide ? r.u16() : r.u8();
+            out.push(wide ? (0, oleobj_1.utf16)(r.bytes(n * 2)) : latin(r.bytes(n)));
+            r.skip(extra);
+        }
+        return out;
+    }, () => out);
+}
+const latin = (b) => Buffer.from(b.buffer, b.byteOffset, b.byteLength).toString('latin1');

package/dist/xls.d.ts

@@ -0,0 +1,27 @@
+import { type BiffRecord } from './biff';
+import type { CfbEntry, CompoundFile } from './cfb';
+import { type RunContext } from './context';
+/** Turns an encrypted record body into its plain bytes. Without encryption the body is as stored. */
+export type Decrypt = (r: BiffRecord) => Uint8Array;
+/**
+ * Opens a workbook encrypted by its FILEPASS record, or says it cannot. Set by the decryption module, so this module
+ * reads workbooks without knowing how they are encrypted.
+ */
+export type Unlock = (ctx: RunContext, filePass: BiffRecord, stream: string) => Decrypt | Promise<Decrypt>;
+/**
+ * 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;
+}>;
+/**
+ * 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.
+ */
+export declare function virtualPath(p: string): string;
+/** The target of an HLink record: its Hyperlink Object (MS-OSHARED 2.3.7.1) after the cell range and class id. */
+export declare function hyperlink(b: Uint8Array): string;

package/dist/xls.js

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.excelRules = excelRules;
+exports.virtualPath = virtualPath;
+exports.hyperlink = hyperlink;
+const biff_1 = require("./biff");
+const context_1 = require("./context");
+const errors_1 = require("./errors");
+const formulas_1 = require("./formulas");
+const links_1 = require("./links");
+const oleobj_1 = require("./oleobj");
+const types_1 = require("./types");
+const STATES = ['visible', 'hidden', 'very hidden', 'hidden'];
+/** Record types of cell formulas (MS-XLS 2.4.127, 2.4.260 and 2.4.4): FORMULA, SHRFMLA and ARRAY. */
+const FORMULA = 0x0006;
+const SHRFMLA = 0x04bc;
+const ARRAY = 0x0221;
+/** Where the parsed formula starts in each: its cce, then its rgce. */
+const FORMULA_AT = new Map([
+    [FORMULA, 20],
+    [SHRFMLA, 8],
+    [ARRAY, 12],
+]);
+/**
+ * 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`.
+ */
+async function excelRules(ctx, cfb, stream, unlock) {
+    const location = stream.name;
+    const records = new biff_1.RecordReader(cfb, stream, 0, ctx.settings.deadline);
+    const first = await records.next();
+    if (first?.type !== biff_1.R.bof || first.body.length < 4)
+        throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, `The ${stream.name} stream does not start with a BOF record`, { reason: 'a workbook stream without a BOF record' });
+    const biff8 = (first.body[0] | (first.body[1] << 8)) === 0x0600;
+    let decrypt = r => r.body;
+    const sheets = [];
+    const books = [];
+    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);
+            continue;
+        }
+        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);
+            const auto = (0, biff_1.autoName)(name.name);
+            if (auto)
+                ctx.report(types_1.OfficeCategory.Macro, auto.onOpen ? types_1.OfficeDetail.EventOnOpen : types_1.OfficeDetail.Event, location, { event: auto.event, name: (0, context_1.clip)(name.name) });
+        }
+        else if (r.type === biff_1.R.supBook && body.length >= 4) {
+            const cch = body[2] | (body[3] << 8);
+            books.push({ ctab: body[0] | (body[1] << 8), cch, path: cch > 0 && cch <= 0xff ? (0, biff_1.xlString)(body, 4, cch).text : '', ole: false, dde: false, names: [] });
+        }
+        else if (r.type === biff_1.R.externSheet && biff8 && body.length >= 2) {
+            const n = body[0] | (body[1] << 8);
+            for (let k = 0; k < n && 2 + k * 6 + 2 <= body.length; k++)
+                xti.push(body[2 + k * 6] | (body[3 + k * 6] << 8));
+        }
+        else if (r.type === biff_1.R.externName && body.length >= 2 && books.length) {
+            if (biff8 && body.length >= 7)
+                books[books.length - 1].names.push((0, biff_1.xlString)(body, 7, body[6]).text);
+            // fOle and fOleLink mark an OLE object's name. Excel writes StdDocumentName with fOle beside the items of a DDE
+            // link, so a link with any DDE item is a DDE link.
+            if ((body[0] | (body[1] << 8)) & 0x18)
+                books[books.length - 1].ole = true;
+            else
+                books[books.length - 1].dde = true;
+        }
+    }
+    for (const b of books)
+        linkRules(ctx, b, location);
+    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) {
+    if (b.cch === 0x401 || b.cch === 0x3a01 || b.path === ' ' || b.path === '\0' || !b.path)
+        return;
+    if (b.ctab === 0) {
+        // A DDE or OLE data source: the application or class, U+0003, and the topic or file.
+        const [application, topic = ''] = b.path.split('\x03');
+        if (b.ole && !b.dde) {
+            const data = { source: 'SupBook', className: (0, context_1.clip)(application) };
+            if (topic)
+                ctx.external(types_1.OfficeDetail.Object, topic, location, data, 'linked object');
+            else
+                ctx.report(types_1.OfficeCategory.External, types_1.OfficeDetail.Object, location, data);
+        }
+        else
+            ctx.report(types_1.OfficeCategory.Dde, types_1.OfficeDetail.Link, location, { application: (0, context_1.clip)(application), topic: (0, context_1.clip)(topic) });
+        return;
+    }
+    ctx.external(types_1.OfficeDetail.Workbook, virtualPath(b.path), location, { source: 'SupBook' }, 'external workbook');
+}
+/**
+ * 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.
+ */
+function virtualPath(p) {
+    if (p.charCodeAt(0) !== 1)
+        return p;
+    let out = '';
+    for (let i = 1; i < p.length; i++) {
+        const c = p.charCodeAt(i);
+        if (c === 1) {
+            // A drive letter, or @ for a UNC host. A U+0003 after it starts the path.
+            const v = p[i + 1] ?? '';
+            i++;
+            out += v === '@' ? '\\\\' : `${v}:`;
+        }
+        else if (c === 2 || c === 3)
+            out += '\\';
+        else if (c === 4)
+            out += '..\\';
+        // A long volume, such as a URL, after a character that counts it.
+        else if (c === 5)
+            i++;
+        else if (c >= 6 && c <= 8)
+            out += 'XLSTART\\';
+        else
+            out += p[i];
+    }
+    return out;
+}
+/** One sheet's substream, with any chart substreams inside it: Obj records that run macros, and hyperlinks. */
+async function sheetRules(ctx, cfb, stream, s, decrypt, location, nameOf) {
+    const records = new biff_1.RecordReader(cfb, stream, s.position, ctx.settings.deadline);
+    const bof = await records.next();
+    if (bof?.type !== biff_1.R.bof || bof.body.length < 4)
+        return;
+    const bofType = bof.body[2] | (bof.body[3] << 8);
+    // The sheet's own BOF says what it is, and so does its BoundSheet record. Either one makes a macro sheet.
+    const macroSheet = s.type === 1 || bofType === 0x0040;
+    if (macroSheet)
+        ctx.report(types_1.OfficeCategory.Macro, types_1.OfficeDetail.XlmMacrosheet, location, { sheet: (0, context_1.clip)(s.name), state: STATES[s.state] });
+    let depth = 1;
+    for (let r = await records.next(); r && depth > 0; r = await records.next()) {
+        if (r.type === biff_1.R.bof)
+            depth++;
+        else if (r.type === biff_1.R.eof)
+            depth--;
+        else if (r.type === biff_1.R.obj) {
+            if (objMacro(decrypt(r)))
+                ctx.report(types_1.OfficeCategory.Macro, types_1.OfficeDetail.Link, location, { sheet: (0, context_1.clip)(s.name) });
+        }
+        else if (r.type === biff_1.R.hlink) {
+            const target = hyperlink(decrypt(r));
+            if (target.trim() && !(0, links_1.isFragment)(target))
+                ctx.link(target, location, { sheet: (0, context_1.clip)(s.name), source: 'HLink record' });
+        }
+        else if (nameOf && !macroSheet && FORMULA_AT.has(r.type)) {
+            // A macro sheet's formulas are its macros, which its own finding covers.
+            const b = decrypt(r);
+            const at = FORMULA_AT.get(r.type) ?? 0;
+            if (b.length < at + 2)
+                continue;
+            const cce = b[at] | (b[at + 1] << 8);
+            for (const [fn, kind] of (0, formulas_1.biffCalls)(b.subarray(at + 2, at + 2 + cce), nameOf))
+                ctx.report(kind === 'fetch' ? types_1.OfficeCategory.External : types_1.OfficeCategory.Macro, types_1.OfficeDetail.Formula, location, { sheet: (0, context_1.clip)(s.name), function: (0, context_1.clip)(fn) });
+        }
+    }
+}
+/** Whether an Obj record (MS-XLS 2.4.181) holds an FtMacro subrecord, the macro a click runs. */
+function objMacro(b) {
+    let at = 0;
+    while (at + 4 <= b.length) {
+        const ft = b[at] | (b[at + 1] << 8);
+        const cb = b[at + 2] | (b[at + 3] << 8);
+        // FtEnd ends the list, and FtLbsData's length does not count all its data, so the walk stops there.
+        if (ft === 0x00 || ft === 0x13)
+            return false;
+        if (ft === 0x04)
+            return cb > 0;
+        at += 4 + cb;
+    }
+    return false;
+}
+/** The target of an HLink record: its Hyperlink Object (MS-OSHARED 2.3.7.1) after the cell range and class id. */
+function hyperlink(b) {
+    const r = new oleobj_1.ByteReader(b);
+    return (0, oleobj_1.bounded)(() => {
+        r.skip(8 + 16 + 4);
+        const flags = r.u32();
+        const string = () => (0, oleobj_1.utf16)(r.bytes(r.u32() * 2)).replace(/\0+$/, '');
+        if (flags & 0x10)
+            string();
+        if (flags & 0x80)
+            string();
+        if (!(flags & 0x01))
+            return '';
+        return flags & 0x100 ? string() : (0, oleobj_1.readMoniker)(r).target;
+    }, () => '');
+}

package/dist/xml.d.ts

@@ -32,6 +32,17 @@ export interface XmlElement {
      */
     start: number;
     end: number;
+    /** The element's position among the elements of the part, from 0, counting those in entity text. */
+    index: number;
+    /** The namespace declarations of the start tag, as prefix ('' for the default namespace) and URI, defaults included. */
+    namespaces: Array<[string, string]>;
+    /** Written as an empty-element tag. */
+    empty: boolean;
+    /**
+     * The start tag does not say on its own what the attributes are: a value refers to an entity the internal subset
+     * declares, or an attribute-list declaration added a default or normalized a value.
+     */
+    rewritten: boolean;
 }
 export interface XmlHandler {
     start?(el: XmlElement): void;
@@ -87,6 +98,12 @@ export interface XmlExternalReference {
 export interface XmlNotes {
     doctype?(d: XmlDoctype): void;
     externalEntity?(r: XmlExternalReference): void;
+    /**
+     * A reference to an internal entity in content, outside any other entity's text, at these offsets. The events of
+     * its text come between this call and `referenceEnd`.
+     */
+    referenceStart?(start: number, end: number): void;
+    referenceEnd?(): void;
 }
 export interface XmlOptions {
     /** Reads the dialect Office writes in VML drawing parts. See XmlTokenizer. */
@@ -99,6 +116,15 @@ export interface XmlOptions {
 export declare function attr(el: XmlElement, ns: string, local: string): string | undefined;
 /** An XML name without a colon. */
 export declare const isNcName: (s: string) => boolean;
+export type XmlEncoding = 'utf-8' | 'utf-16le' | 'utf-16be';
+/**
+ * The encoding of an XML part from its first four bytes, as XML 1.0 Appendix F tells it, and the length of its byte
+ * order mark. Undefined for UTF-32, which no Office application reads.
+ */
+export declare function detectEncoding(b: Uint8Array): {
+    encoding: XmlEncoding;
+    bom: number;
+} | undefined;
 /**
  * A streaming XML 1.0 tokenizer with namespaces. It refuses references to entities nothing declares, encodings other
  * than UTF-8 and UTF-16, and anything not well-formed. It holds one markup token at a time; text goes to the handler
@@ -133,6 +159,10 @@ export declare class XmlTokenizer {
     /** The XML declaration says standalone="yes". */
     private standalone;
     private encoding;
+    /** 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. */
+    private generalReference;
     /** The last text piece ended in CR, so an LF that starts the next piece belongs to the same line end. */
     private lastCr;
     private scan?;

package/dist/xml.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.XmlTokenizer = exports.isNcName = exports.unknownEntity = exports.showReferences = exports.UNKNOWN = exports.XMLNS_NS = exports.XML_NS = void 0;
 exports.attr = attr;
+exports.detectEncoding = detectEncoding;
 const node_util_1 = require("node:util");
 const errors_1 = require("./errors");
 const types_1 = require("./types");
@@ -53,6 +54,26 @@ const NAME_END = /[\s>[\]"'%;&<]/;
 /** Attribute types other than CDATA, whose values are normalized further. NOTATION and enumerations are read apart. */
 const TOKENIZED_TYPES = new Set(['ID', 'IDREF', 'IDREFS', 'ENTITY', 'ENTITIES', 'NMTOKEN', 'NMTOKENS']);
 const LIMIT_DETAILS = new Set([types_1.OfficeDetail.XmlDepth, types_1.OfficeDetail.XmlTokenSize, types_1.OfficeDetail.XmlEntityDepth, types_1.OfficeDetail.XmlEntityExpansions, types_1.OfficeDetail.XmlEntitySize]);
+/**
+ * The encoding of an XML part from its first four bytes, as XML 1.0 Appendix F tells it, and the length of its byte
+ * order mark. Undefined for UTF-32, which no Office application reads.
+ */
+function detectEncoding(b) {
+    const at = (i) => (i < b.length ? b[i] : -1);
+    if ((at(0) === 0 && at(1) === 0) || (at(0) === 0xff && at(1) === 0xfe && at(2) === 0 && at(3) === 0) || (at(0) === 0x3c && at(1) === 0 && at(2) === 0 && at(3) === 0))
+        return undefined;
+    if (at(0) === 0xef && at(1) === 0xbb && at(2) === 0xbf)
+        return { encoding: 'utf-8', bom: 3 };
+    if (at(0) === 0xff && at(1) === 0xfe)
+        return { encoding: 'utf-16le', bom: 2 };
+    if (at(0) === 0xfe && at(1) === 0xff)
+        return { encoding: 'utf-16be', bom: 2 };
+    if (at(0) === 0x3c && at(1) === 0 && at(2) === 0x3f && at(3) === 0)
+        return { encoding: 'utf-16le', bom: 0 };
+    if (at(0) === 0 && at(1) === 0x3c && at(2) === 0 && at(3) === 0x3f)
+        return { encoding: 'utf-16be', bom: 0 };
+    return { encoding: 'utf-8', bom: 0 };
+}
 const isSpace = (c) => c === 0x20 || c === 0x09 || c === 0x0a || c === 0x0d;
 /** A character XML 1.0 allows. The decoders leave no lone surrogates, so the halves of a pair pass here. */
 const isXmlChar = (c) => c === 0x09 || c === 0x0a || c === 0x0d || (c >= 0x20 && c !== 0xfffe && c !== 0xffff);
@@ -169,6 +190,10 @@ class XmlTokenizer {
     /** The XML declaration says standalone="yes". */
     standalone = false;
     encoding = 'utf-8';
+    /** 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. */
+    generalReference = false;
     /** The last text piece ended in CR, so an LF that starts the next piece belongs to the same line end. */
     lastCr = false;
     scan;
@@ -227,29 +252,14 @@ class XmlTokenizer {
     /** Picks the encoding from the first bytes, as XML 1.0 Appendix F does, and reads the bytes held so far. */
     begin() {
         const b = this.head;
-        const at = (i) => (i < b.length ? b[i] : -1);
-        if ((at(0) === 0 && at(1) === 0) || (at(0) === 0xff && at(1) === 0xfe && at(2) === 0 && at(3) === 0) || (at(0) === 0x3c && at(1) === 0 && at(2) === 0 && at(3) === 0)) {
-            this.stop(types_1.OfficeDetail.Encoding, 'UTF-32 is not an encoding Office reads');
-        }
-        let skip = 0;
-        if (at(0) === 0xef && at(1) === 0xbb && at(2) === 0xbf)
-            skip = 3;
-        else if (at(0) === 0xff && at(1) === 0xfe) {
-            this.encoding = 'utf-16le';
-            skip = 2;
-        }
-        else if (at(0) === 0xfe && at(1) === 0xff) {
-            this.encoding = 'utf-16be';
-            skip = 2;
-        }
-        else if (at(0) === 0x3c && at(1) === 0 && at(2) === 0x3f && at(3) === 0)
-            this.encoding = 'utf-16le';
-        else if (at(0) === 0 && at(1) === 0x3c && at(2) === 0 && at(3) === 0x3f)
-            this.encoding = 'utf-16be';
+        const found = detectEncoding(b);
+        if (!found)
+            return this.stop(types_1.OfficeDetail.Encoding, 'UTF-32 is not an encoding Office reads');
+        this.encoding = found.encoding;
         const decoder = new node_util_1.TextDecoder(this.encoding, { fatal: true, ignoreBOM: true });
         this.decoder = decoder;
         this.head = new Uint8Array(0);
-        this.feed(this.decode(decoder, b.subarray(skip), true), false);
+        this.feed(this.decode(decoder, b.subarray(found.bom), true), false);
         return decoder;
     }
     decode(decoder, bytes, more) {
@@ -467,6 +477,8 @@ class XmlTokenizer {
             return;
         }
         this.enter(name, e.text);
+        if (!this.span)
+            this.notes.referenceStart?.(start, end);
         const { buf, pos, base, floor, span: outer } = this;
         this.buf = e.text;
         this.pos = 0;
@@ -482,6 +494,8 @@ class XmlTokenizer {
         this.floor = floor;
         this.span = outer;
         this.active.pop();
+        if (!outer)
+            this.notes.referenceEnd?.();
     }
     /** A reference to a general entity in an attribute value. Its text is normalized into the value. */
     attributeReference(name) {
@@ -489,6 +503,7 @@ class XmlTokenizer {
         if (!('text' in e))
             this.malformed(`A reference to external entity "${name}" in an attribute value`);
         this.enter(name, e.text);
+        this.generalReference = true;
         const value = this.attributeValue(e.text, true);
         this.active.pop();
         return value;
@@ -981,6 +996,7 @@ class XmlTokenizer {
         const qname = body.slice(0, i);
         const raw = [];
         let selfClosing = this.vml && qname.toLowerCase() === 'br';
+        this.generalReference = false;
         for (;;) {
             const before = i;
             while (i < n && isSpace(body.charCodeAt(i)))
@@ -1017,18 +1033,24 @@ class XmlTokenizer {
         // Attribute-list declarations normalize the attributes they type, and add the defaults the tag leaves out. Each
         // default added counts against the entity limits, so declarations cannot multiply the work of a long part.
         const declared = this.declared.get(qname);
+        let rewritten = this.generalReference;
         if (declared) {
             const given = new Set();
             for (const a of raw) {
                 given.add(a[0]);
-                if (declared.tokenized.has(a[0]))
-                    a[1] = tokenize(a[1]);
+                if (!declared.tokenized.has(a[0]))
+                    continue;
+                const v = tokenize(a[1]);
+                if (v !== a[1])
+                    rewritten = true;
+                a[1] = v;
             }
             for (const [name, value] of declared.defaults) {
                 if (given.has(name))
                     continue;
                 this.charge(value.length);
                 raw.push([name, value]);
+                rewritten = true;
             }
         }
         const scope = new Map();
@@ -1061,7 +1083,7 @@ class XmlTokenizer {
         const depth = this.stack.length + 1;
         if (depth > this.limits.depth)
             this.stop(types_1.OfficeDetail.XmlDepth, `Elements nest deeper than ${this.limits.depth}`);
-        const el = { ns: '', local: '', qname, attributes: [], depth, start, end };
+        const el = { ns: '', local: '', qname, attributes: [], depth, start, end, index: this.elements++, namespaces: [...scope], empty: selfClosing, rewritten };
         const open = { el, scope: scope.size ? scope : undefined };
         this.stack.push(open);
         const [prefix, local] = this.split(qname);

package/dist/zip-writer.d.ts

@@ -24,6 +24,8 @@ export declare class ZipWriter {
     constructor(sink: ByteSink, options?: {
         forceZip64?: boolean;
     });
+    /** Bytes written so far: where the next entry's local header goes. */
+    get position(): number;
     private put;
     /** Adds an entry from bytes in memory, deflated unless `compress` is false. A name ending in "/" is a directory. */
     add(name: string, data: Uint8Array, options?: {
@@ -31,6 +33,8 @@ export declare class ZipWriter {
         dosTime?: number;
         dosDate?: number;
     }): Promise<void>;
+    /** The local header `copy` writes for an entry. */
+    localHeader(info: CopiedEntry): Uint8Array;
     /** Adds an entry whose compressed bytes come from `chunks` unchanged, such as an entry of the archive being rewritten. */
     copy(info: CopiedEntry, chunks: AsyncIterable<Uint8Array>): Promise<void>;
     /** Writes the central directory and the end records. The caller closes the sink. */