@patrickdk77/office-defuse 0.1.1 → 0.2.1

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,9 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWordTemplate = isWordTemplate;
 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). */
@@ -14,27 +16,56 @@ 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;
+/**
+ * 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) {
-    const source = cfb.source(stream);
-    const fib = await source.read(0, 1024);
-    const ident = fib.length >= 32 ? u16(fib, 0) : 0;
-    if (ident !== WORD8 && ident !== WORD6) {
+    let source = cfb.source(stream);
+    let fib = await source.read(0, 1024);
+    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);
-    // fEncrypted, set for both RC4 encryption and XOR obfuscation.
-    if (flags & 0x0100)
-        throw new errors_1.StopError(types_1.OfficeCategory.Encrypted, types_1.OfficeDetail.PasswordRequired, 'The document is encrypted', { stream: stream.name });
+    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
+    // 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
@@ -47,28 +78,45 @@ async function wordRules(ctx, cfb, stream, optional = false) {
                 fields.separate();
             else if (ch === '\x15')
                 fields.end();
-            else if (fields.inCode && (ch >= ' ' || ch === '\t'))
-                fields.text(ch);
+            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 from fcMin to fcMac. A file saved fast adds pieces to the
-        // end, and this reads every byte between, as msodde does.
-        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))));
+        // 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 = cfb.child(cfb.root, flags & 0x0200 ? '1Table' : '0Table');
-        if (table?.kind === 'stream') {
-            const tableSource = cfb.source(table);
+        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))) {
@@ -92,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,15 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.workbookKind = workbookKind;
 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],
+]);
+/**
+ * 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
@@ -26,7 +57,9 @@ async function excelRules(ctx, cfb, stream, unlock) {
     let decrypt = r => r.body;
     const sheets = [];
     const books = [];
-    const flags = { template: false, addIn: false };
+    const names = [];
+    /** The SupBook each XTI of the ExternSheet record names. */
+    const xti = [];
     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);
@@ -35,21 +68,25 @@ 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);
             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 });
+            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)
@@ -60,9 +97,9 @@ async function excelRules(ctx, cfb, stream, unlock) {
     }
     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);
-    return flags;
+        await sheetRules(ctx, cfb, stream, s, decrypt, location, biff8 ? nameOf : undefined);
 }
 /** A SupBook record, read as MS-XLS 2.4.271 and oletools tell its kinds apart. */
 function linkRules(ctx, b, location) {
@@ -115,14 +152,15 @@ function virtualPath(p) {
     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) {
+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.
-    if (s.type === 1 || bofType === 0x0040)
+    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()) {
@@ -139,6 +177,16 @@ async function sheetRules(ctx, cfb, stream, s, decrypt, location) {
             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. */

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. */

package/dist/zip-writer.js

@@ -76,6 +76,10 @@ class ZipWriter {
         this.sink = sink;
         this.options = options;
     }
+    /** Bytes written so far: where the next entry's local header goes. */
+    get position() {
+        return this.offset;
+    }
     async put(b) {
         await this.sink.write(b);
         this.offset += b.length;
@@ -89,15 +93,11 @@ class ZipWriter {
             yield body;
         })());
     }
-    /** Adds an entry whose compressed bytes come from `chunks` unchanged, such as an entry of the archive being rewritten. */
-    async copy(info, chunks) {
-        if (this.names.has(info.name))
-            throw new Error(`Entry ${info.name} is already in the archive`);
-        this.names.add(info.name);
+    /** The local header `copy` writes for an entry. */
+    localHeader(info) {
         const name = Buffer.from(info.name, 'utf8');
         const flags = /^[\x20-\x7e]*$/.test(info.name) ? 0 : 0x0800;
         const big = this.options.forceZip64 === true || info.size >= MAX32 || info.compressedSize >= MAX32;
-        const localOffset = this.offset;
         const time = info.dosTime ?? 0;
         const date = info.dosDate ?? DOS_DATE;
         const local = new Builder()
@@ -115,7 +115,20 @@ class ZipWriter {
             .bytes(name);
         if (big)
             local.u16(0x0001).u16(16).u64(info.size).u64(info.compressedSize);
-        await this.put(local.build());
+        return local.build();
+    }
+    /** Adds an entry whose compressed bytes come from `chunks` unchanged, such as an entry of the archive being rewritten. */
+    async copy(info, chunks) {
+        if (this.names.has(info.name))
+            throw new Error(`Entry ${info.name} is already in the archive`);
+        this.names.add(info.name);
+        const name = Buffer.from(info.name, 'utf8');
+        const flags = /^[\x20-\x7e]*$/.test(info.name) ? 0 : 0x0800;
+        const big = this.options.forceZip64 === true || info.size >= MAX32 || info.compressedSize >= MAX32;
+        const localOffset = this.offset;
+        const time = info.dosTime ?? 0;
+        const date = info.dosDate ?? DOS_DATE;
+        await this.put(this.localHeader(info));
         let written = 0;
         for await (const c of chunks) {
             written += c.length;

package/dist/zip.d.ts

@@ -27,10 +27,17 @@ export interface ZipEntry {
 }
 /** Something the reader saw that it does not refuse. Each is a strip finding, since the rewrite drops the bytes. */
 export interface ZipNote {
-    detail: D.LeadingBytes | D.HiddenData | D.TrailingBytes;
+    detail: D.LeadingBytes | D.HiddenData | D.HiddenEntry | D.TrailingBytes;
     bytes: number;
+    /** For a hidden entry, where its local header sits. */
+    offset?: number;
 }
-/** The key two names collide on: percent-decoded, NFC and lowercase, without a directory's slash. */
+/**
+ * The key two names collide on: percent-decoded, NFKC and case-folded, without a directory's slash, and without the
+ * dots and spaces Windows drops from the end of each segment. Upper then lower case is the full folding, which takes a
+ * sharp s to ss as macOS's case-insensitive file system does. NFKC also joins compatibility forms such as ligatures
+ * and full-width letters.
+ */
 export declare function nameKey(name: string): string;
 /**
  * A ZIP archive read from its central directory, after every local header was checked against it. Reading an entry
@@ -41,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. */