@patrickdk77/office-defuse 0.1.0 → 0.1.1

package/README.md

@@ -1,16 +1,16 @@
 # office-defuse
 
-office-defuse reads Word, Excel, PowerPoint, Visio and OpenDocument packages and reports VBA and Excel 4.0 macros, LibreOffice Basic and scripts, DDE, fields and events that run code, templates and objects loaded from outside the file, embedded OLE objects, ActiveX controls and unsafe links. It scores the risk from 0 to 100.
+office-defuse reads Word, Excel, PowerPoint and Visio files, in their ZIP formats and in the compound file formats before them, OpenDocument packages, Outlook messages, Publisher and Project files, and RTF. It reports VBA, WordBasic and Excel 4.0 macros, LibreOffice Basic and scripts, DDE, fields and events that run code, templates and objects loaded from outside the file, embedded OLE objects, Equation Editor objects, attachments, ActiveX controls and unsafe links. It scores the risk from 0 to 100.
 
 This version inspects and changes nothing.
 
-It has no runtime dependencies and keeps memory bounded. It reads the ZIP and XML containers strictly, and refuses anything two readers could take in different ways.
+It has no runtime dependencies and keeps memory bounded. It reads ZIP archives, compound files and XML strictly, and refuses anything two readers could take in different ways. RTF it reads the way Word does, quirks included.
 
 ```
 npm install @patrickdk77/office-defuse
 ```
 
-Node 22 or later.
+Node 18 or later.
 
 ## Quick start
 
@@ -21,14 +21,14 @@ const report = await inspectOffice(bytes);
 report.status;   // 'clean', 'strippable' or 'rejected'
 report.risk;     // 'NONE', 'LOW', 'MEDIUM', 'HIGH', 'CRITICAL' or 'UNKNOWN'
 report.score;    // 0 to 100, null when the file could not be inspected
-report.format;   // 'docx', 'xlsm', 'odt', ... or '' when not recognized
+report.format;   // 'docx', 'xls', 'msg', 'rtf', ... or '' when not recognized
 report.mimeType; // the MIME type of that format, or ''
 report.findings; // [{ category, detail, description, action, location, data }]
 ```
 
 ES modules work too: `import { inspectOffice } from '@patrickdk77/office-defuse'`.
 
-`strippable` means at least one finding has the action `strip`, content a defused copy would leave out. `rejected` means a finding has the action `reject`, or the run stopped before it read the whole package.
+`strippable` means at least one finding has the action `strip`, content a defused copy would leave out. `rejected` means a finding has the action `reject`, or the run stopped before it read the whole file.
 
 ### Files and S3
 
@@ -52,13 +52,16 @@ await inspectOfficeSource(source);
 
 The format comes from the content, never from the file name.
 
-| Family | Formats |
-|---|---|
-| Word | .docx .docm .dotx .dotm |
-| Excel | .xlsx .xlsm .xltx .xltm .xlam .xlsb |
-| PowerPoint | .pptx .pptm .potx .potm .ppsx .ppsm .ppam .sldx .sldm |
-| Visio | .vsdx .vsdm .vstx .vstm .vssx .vssm |
-| OpenDocument | .odt .ott .ods .ots .odp .otp .odg .otg .odf .odm .odb |
+| Family | ZIP formats | Compound file and RTF formats |
+|---|---|---|
+| Word | .docx .docm .dotx .dotm | .doc .dot from Word 6.0 to 2003, and .rtf |
+| Excel | .xlsx .xlsm .xltx .xltm .xlam .xlsb | .xls .xlt .xla from Excel 5.0 to 2003 |
+| PowerPoint | .pptx .pptm .potx .potm .ppsx .ppsm .ppam .sldx .sldm | .ppt from PowerPoint 97 to 2003 |
+| Visio | .vsdx .vsdm .vstx .vstm .vssx .vssm | .vsd from Visio 2003 to 2010 |
+| OpenDocument | .odt .ott .ods .ots .odp .otp .odg .otg .odf .odm .odb | |
+| Outlook | | .msg .oft |
+| Publisher | | .pub |
+| Project | | .mpp |
 
 `[Content_Types].xml` marks an Office Open XML package. The package relationship of type `officeDocument`, transitional or strict, or Visio's `document`, names the main part, and its content type gives the format. The `mimetype` entry marks an OpenDocument package, or the manifest's entry for `/` when there is no mimetype entry.
 
@@ -66,11 +69,22 @@ A ZIP with both markers is rejected as PACKAGE/AMBIGUOUS_FORMAT, since Office co
 
 A .xlsb gets the package checks. Its sheets are binary records, and the formulas in them go unread. Its external link parts are binary too, and office-defuse reads their link records for DDE links. A .odb gets every ODF check, and the database under `database/` goes unread.
 
+A file that starts with the compound file signature is a compound file, MS-CFB. The streams and storages at its root name the format: `WordDocument` for Word, `Workbook` or `Book` for Excel, `PowerPoint Document`, `VisioDocument`, `__properties_version1.0` for an Outlook message, a `Quill` storage or Publisher's class id beside a `Contents` stream for Publisher, and a `Props` stream beside a storage named by a number for Project. Word's FIB says whether a document is a template, and Excel's records whether a workbook is a template or an add-in. An Outlook template has a class id of its own. A PowerPoint 97 to 2003 template or show reports its format as .ppt, and a Visio stencil or template as .vsd.
+
+A compound file with two of these is PACKAGE/AMBIGUOUS_FORMAT. One with none is PACKAGE/UNRECOGNIZED, and so is a `WordDocument` stream that holds no Word 6.0 to 2003 FIB. A PowerPoint 4.0 file, a bare OLE object and a `vbaProject.bin` on its own all land there.
+
+An encrypted .docx, .xlsx or .pptx is a compound file holding `EncryptionInfo` and `EncryptedPackage`. See [Encrypted files](#encrypted-files).
+
+A file that starts with `{\rt` is RTF, as Word takes it. A compound file or RTF file in which the ZIP reader also finds an archive is PACKAGE/AMBIGUOUS_FORMAT. A file with the compound file signature whose compound file does not read, but whose ZIP archive does, is that ZIP archive with LEADING_BYTES.
+
 ## What it reports
 
-- VBA projects, Excel 4.0 macro sheets, and OpenDocument `Basic/`, `Scripts/` and `Dialogs/` folders. These go by content type, relationship type or folder name, and a folder counts when it holds a file that is not empty. office-defuse parses nothing inside an OLE file such as `vbaProject.bin`.
+In a ZIP package:
+
+- VBA projects, Excel 4.0 macro sheets, and OpenDocument `Basic/`, `Scripts/` and `Dialogs/` folders. These go by content type, relationship type or folder name, and a folder counts when it holds a file that is not empty. office-defuse parses no OLE part of a package, such as `vbaProject.bin`.
 - OpenDocument script event listeners that name a script URL or macro. Those that fire as the document opens or is created get a finding of their own. LibreOffice ignores a listener whose URL and macro name are both empty, and so does office-defuse. Visio ShapeSheet cells that call RUNADDON, RUNADDONWARGS, CALLTHIS, RUNMACRO, OPENFILE or DOOLEVERB.
 - Links and actions that run macros: `vnd.sun.star.script:` and `macro:` targets, PowerPoint's `ppaction://macro`, Excel drawing shapes with a `macro` attribute, and form controls with an `x:FmlaMacro`. Ribbon callbacks such as `onLoad` and `onAction`. OpenDocument menu, toolbar and key settings under `Configurations2/`. LibreOffice writes an empty `Configurations2/accelerator/current.xml` into the documents it saves, and an empty file counts for nothing.
+- Excel defined names that run a macro sheet: Auto_Open and Auto_Activate as MACRO/EVENT_ON_OPEN, Auto_Close and Auto_Deactivate as MACRO/EVENT. A name counts when it starts with one of these, as `Auto_Open2` does.
 - PowerPoint and Impress actions that run a program or an object verb.
 - DDE: Word `DDE` and `DDEAUTO` fields, Excel `ddeLink` parts and the .xlsb record for them, Excel formulas in `application|topic!item` form, OpenDocument DDE connections and `DDE()` formulas. No amount of white space before a field's name hides it, and a formula is checked whole however long it runs.
 - Word fields that run a macro, `MACROBUTTON`, and fields whose type another field builds. That is the QUOTE trick that hides `DDEAUTO`.
@@ -82,6 +96,38 @@ A .xlsb gets the package checks. Its sheets are binary records, and the formulas
 
 The OOXML rules match elements by namespace URI and local name, compared ignoring case, so a prefix bound to the Word namespace reads as Word whatever it is called. The OpenDocument rules read `urn:oasis:names:tc:<any>:xmlns:<name>:1.<any>` as version 1.0 of that namespace, which is what LibreOffice does. Every branch of `mc:AlternateContent` gets read.
 
+In a compound file, the first two rules run over every storage of the tree, and the others over the streams of the format:
+
+- VBA projects: a `VBA` storage with a `dir` stream, or a `_VBA_PROJECT_CUR` or `Macros` storage with something in it.
+- Embedded objects, by the streams an object's storage holds, under `ObjectPool` or anywhere else: OLE objects with their class id, ProgID and user type, the file a Packager object holds, Equation Editor 3.0 objects by class id or ProgID, ActiveX controls, and linked objects with the target their moniker names. An object's storage is part of the tree, so a macro or an object inside an object is found.
+- Word: WordBasic macros in Word 6.0 and 95 files. The fields of the text, with the rules a .docx gets, and the attached template.
+- Excel: Excel 4.0 macro sheets, by sheet type or by the sheet's own BOF record, and the Auto_ names above, built in or defined. External workbooks, with the paths Excel encodes written out, DDE and OLE links, hyperlinks, shapes and buttons that run a macro, and the `Ctls` stream that holds ActiveX controls.
+- PowerPoint: actions that run a macro, a program or an object verb, hyperlinks, and linked sounds and movies. PowerPoint keeps the storages of objects, controls and the VBA project in its document stream, often compressed. office-defuse inflates them and gives them the rules above.
+- Outlook: each attachment, as EMBEDDED/ATTACHMENT with its name, MIME type and size, and each attachment by reference with its path. An attached message's own attachments are read, 16 messages deep.
+- Visio, Publisher and Project: the VBA projects and objects. Nothing in their own streams is read.
+
+In RTF:
+
+- Objects in `\objdata`. office-defuse decodes the OLE 1.0 object, the file a Packager object holds, and the storage of an OLE 2 object, which gets the compound file rules. An object linked with `\objlink` or `\objautlink`, or of the class OLE2Link that CVE-2017-0199 uses, is EXTERNAL/OBJECT. `\objocx` marks an ActiveX control. `\objupdate` is ACTION/OBJECT_UPDATE, since it starts the object's program as the document opens.
+- Fields, with the rules a .docx gets, the `\*\template` destination, and shape hyperlinks.
+- Text after the group that closes the document, as TRAILING_BYTES. White space and NULs there are what writers leave, and count for nothing.
+
+### Encrypted files
+
+office-defuse decrypts an OOXML package encrypted with Standard or Agile encryption, MS-OFFCRYPTO, and an .xls workbook encrypted with RC4 or RC4 CryptoAPI. It tries the `password` option first, then VelvetSweatshop, the password Excel tries on its own, so such a workbook opens without asking. The decrypted file gets every check of its format. It is read in place. Agile encryption decrypts in 4,096-byte segments and Standard in 16-byte blocks, so only the parts office-defuse reads get decrypted.
+
+| Finding | Action | Weight | When |
+|---|---|---|---|
+| ENCRYPTED/DEFAULT_PASSWORD | `strip` | 10 | VelvetSweatshop opened the file. Anyone can open it, so the encryption hides its content from a scanner and from no one else |
+| ENCRYPTED/USER_PASSWORD | `strip` | 0 | The password the caller gave opened the file |
+| ENCRYPTED/RC4_40, RC4_128, RC4_OTHER, AES_128, AES_192, AES_256 | `info` | 0 | The cipher and key size |
+| ENCRYPTED/PASSWORD_REQUIRED | `reject` | 0 | No password at hand opens the file, or an Agile spin count is above 10,000,000. Every encrypted .doc and .ppt, which office-defuse does not decrypt |
+| ENCRYPTED/UNSUPPORTED_ALGORITHM | `reject` | 0 | Excel's XOR obfuscation, or a cipher or hash outside the list below |
+
+AES-128, AES-192 and AES-256 in CBC or ECB mode, SHA-1, SHA-256, SHA-384, SHA-512 and MD5 go to Node's crypto module, and no other algorithm name from a file reaches it. RC4 is office-defuse's own code, since OpenSSL 3 keeps RC4 in its legacy provider.
+
+Pass the password in code, never on a command line, where other users can read it.
+
 ## The containers
 
 The ZIP reader starts from the end record and the central directory. It checks each local header against the central directory before it reads any content. It refuses these, and stops the run:
@@ -121,6 +167,39 @@ The `Basic/`, `Scripts/`, `Dialogs/` and `Configurations2/` folders of an OpenDo
 
 PowerPoint and Excel write VML drawings that are not well-formed XML. They put `<![if gte mso 9]>` and `<![endif]>` around content, and Excel 2007 leaves `<br>` unclosed in a button's text. office-defuse reads a part of the VML drawing type in that dialect. It skips the markers, so the content on both sides of them reaches the rules, and it takes `<br>` as an empty element. Apart from those two, it reads the part as strictly as any other.
 
+### Compound files
+
+The compound file reader follows MS-CFB, and where MS-CFB leaves room, it accepts what olefile and LibreOffice accept. It reads the header, the FAT through the DIFAT, the directory, the mini FAT and the mini stream, and records which stream owns each sector, so no sector serves two. It follows a stream's chain only as far as the stream's size needs, as olefile and LibreOffice do, so a chain that runs on past that does no harm. It refuses these, and stops the run:
+
+| Detail | Refused |
+|---|---|
+| BAD_HEADER | A file shorter than its header, a version and sector size other than 3 with 512 bytes or 4 with 4,096, mini sectors other than 64 bytes, a mini stream cutoff other than 4,096, a byte order other than little-endian, FAT or DIFAT sector counts that disagree with the sectors listed, a mini FAT too short for the mini stream, or an empty directory |
+| OUT_OF_RANGE | A sector or a stream outside the file, a directory entry that names one past the directory, or a stream size larger than a JavaScript number holds exactly |
+| OVERLAP | A sector or mini sector that two streams take, or a stream and the FAT, DIFAT, directory or mini FAT |
+| CHAIN_LOOP | A FAT, DIFAT or mini FAT chain that comes back to a sector it took already |
+| BROKEN_CHAIN | A chain that runs into a free or reserved sector before its stream ends, or a DIFAT chain that does not end after its last sector |
+| DATA_ERROR | A chain that ends before its stream does |
+| DIRECTORY_LOOP | A directory entry the tree reaches twice |
+| BAD_ENTRY | An entry in the tree of an unknown or unused type, a root entry that is not the first, a name length or terminator that does not fit, a NUL in a name, or a stream with children |
+| UNSAFE_NAME | A name holding `/`, `\`, `:` or `!`, which MS-CFB forbids |
+| DUPLICATE_NAME | Two entries of one storage whose names are equal ignoring case |
+
+It reports two more without stopping, each `strip`. HIDDEN_DATA counts the bytes that no stream covers and that are not zero: sectors no chain takes, the rest of each stream's last sector or mini sector, mini sectors no stream takes, directory entries the tree does not reach, and the padding of a version 4 header. Zeros are padding and count for nothing. TRAILING_BYTES is data past the last sector the FAT describes. HIDDEN_DATA is common in real files. LibreOffice, for one, leaves an old copy of a directory sector in a free sector when it saves.
+
+`limits.entries` counts directory entries, `limits.decompressedBytes` bounds the size of one stream, and `limits.totalDecompressedBytes` the sizes of all streams together, the way they count ZIP entries. The reader holds the FAT, the mini FAT, the directory and the owner of each sector, and reads streams in ranges as the rules ask for them.
+
+### RTF
+
+The RTF reader takes the file in 256 KiB pieces. It holds the destinations open at the point it has reached, the short text it collects, such as a class name or a template path, and the data of each object it decodes. It reads the way Word reads:
+
+- A control word's name and its number each end after 250 characters.
+- A destination that `\*` marks and that office-defuse does not know is skipped with its group, and an unknown control word is ignored. Every destination of RTF 1.9.1 is known, so a decoy group such as `{\listtable 4142}` inside an object's data adds no hex digits.
+- In an object's data, anything but hex digits drops out, a digit left unpaired before `\'hh` is dropped, and `\bin` data goes in as its bytes.
+- Inside an object's data, a group that `\*` marks and that opens with a control word that is no destination, such as `{\*\par574 0}`, still holds hex digits for rtfobj, and Word opens files that hide an object's data that way. When the data reads differently with and without those groups, both readings get the object rules, and the findings from the second have `reading` in their data.
+- A file can end inside groups, and the reader closes them. Text after the group that closes the document is still read, as rtfobj reads it.
+
+`limits.rtfDepth`, 256 by default, bounds group nesting and the destinations open at once. Past it the run stops with LIMIT/RTF_DEPTH. One object's decoded data counts against `limits.decompressedBytes`, and all of them together against `limits.totalDecompressedBytes`.
+
 ### Document types and entities
 
 office-defuse never loads an external DTD and never fetches an external entity. A document type declaration does not stop the run.
@@ -143,11 +222,11 @@ Three limits bound what a document type can cost: entity references nested 16 de
 
 ### When a run stops
 
-A run that stops rejects the file with a null score and the UNKNOWN level, whatever `actionOverrides` say about the finding that stopped it. The containers, a limit, an unrecognized or ambiguous format, an encrypted OpenDocument package and an unexpected error, PACKAGE/UNREADABLE, all stop a run. The findings made before the stop stay in the report.
+A run that stops rejects the file with a null score and the UNKNOWN level, whatever `actionOverrides` say about the finding that stopped it. The container refusals, a limit, an unrecognized or ambiguous format, an encrypted file that no password at hand opens or whose algorithm office-defuse does not decrypt, and an unexpected error, PACKAGE/UNREADABLE, all stop a run. The findings made before the stop stay in the report.
 
 ## Findings
 
-Every finding has a `category` and a `detail`, plain strings such as `MACRO` and `VBA_PROJECT`, and a `description` that is safe to show the uploader. A description that quotes a value from the file cuts it to 60 characters and shows control and format characters as `?`. `data` keeps a value from the file up to 200 characters, or 2,000 for a target, and `location` names the part, the relationship or the folder.
+Every finding has a `category` and a `detail`, plain strings such as `MACRO` and `VBA_PROJECT`, and a `description` that is safe to show the uploader. A description that quotes a value from the file cuts it to 60 characters and shows control and format characters as `?`. `data` keeps a value from the file up to 200 characters, or 2,000 for a target, and `location` names the part, the relationship, the folder, the stream or storage, or the RTF object's offset.
 
 ```js
 { category: 'EXTERNAL', detail: 'TEMPLATE', description: 'The document loads its template from https://templates.example.net/report.dotm', action: 'strip', location: 'word/_rels/settings.xml.rels, rIdTpl', data: { target: '...', type: '...' } }
@@ -165,7 +244,7 @@ await inspectOffice(bytes, { actionOverrides: [{ category: 'MACRO', action: 'rej
 
 The method is pdf-defuse's. Each kind of finding has a weight: a program run by a click is 80, VBA is 70, a safe link is 0. The highest weight counts in full, every other kind adds a quarter of its weight, and repeats of one kind count once.
 
-Three combinations add more. Code here means macros or DDE. Code or a run-program action together with a template, object or include from outside adds 20. Code with an embedded object or ActiveX control adds 15. Code with leading, hidden or trailing archive data adds 10. The total is capped at 100.
+Three combinations add more. Code here means macros or DDE. Code or a run-program action together with a template, object or include from outside adds 20. Code with an embedded object or ActiveX control adds 15. Code with leading, hidden or trailing container data adds 10. The total is capped at 100.
 
 The bands are NONE at 0, LOW from 1, MEDIUM from 25, HIGH from 50 and CRITICAL from 80. `scoreWeights` and `scoreBands` change them. A finding of a kind office-defuse does not make, such as one from another package, scores at its `weight`, or 0 without one.
 
@@ -174,19 +253,21 @@ The bands are NONE at 0, LOW from 1, MEDIUM from 25, HIGH from 50 and CRITICAL f
 | Option | Default | Purpose |
 |---|---|---|
 | `limits.fileSize` | none | Bytes in the upload, checked before any read |
-| `limits.entries` | 10,000 | Entries in the central directory |
-| `limits.decompressedBytes` | 512 MiB | The declared size of any one entry |
-| `limits.totalDecompressedBytes` | 2 GiB | The declared sizes of all entries together |
+| `limits.entries` | 10,000 | Entries in the central directory, or in a compound file's directory |
+| `limits.decompressedBytes` | 512 MiB | The declared size of any one entry or stream, one RTF object's decoded data, or one compressed PowerPoint storage |
+| `limits.totalDecompressedBytes` | 2 GiB | The declared sizes of all entries, or of all streams, together, and all RTF objects' decoded data |
 | `limits.xmlDepth` | 256 | Element nesting in one XML part |
 | `limits.xmlTokenSize` | 16 Mi | Characters in one tag, comment, processing instruction or CDATA section. A document type declaration counts as one. Text goes through in pieces and has no limit |
 | `limits.xmlEntityDepth` | 16 | Entity references nested inside entity text |
 | `limits.xmlEntityExpansions` | 100,000 | Entity references expanded, and attribute defaults added, in the whole run |
 | `limits.xmlEntitySize` | 16 Mi | Characters of entity text and attribute defaults expanded in the whole run |
+| `limits.rtfDepth` | 256 | Group nesting in an RTF file, and destinations open at once |
 | `limits.timeMs` | none | The whole run |
+| `password` | none | Tried first on an encrypted OOXML package or .xls workbook, before VelvetSweatshop |
 | `actionOverrides` | none | Change the action for a category, or for a category and detail |
 | `scoreWeights`, `scoreBands` | built in | Change the scoring |
 
-The eight limits with a default bound the memory or work any input can cost, so they apply unless you set them. `Infinity` turns one off. A limit that is reached stops the run with a LIMIT finding.
+The nine limits with a default bound the memory or work any input can cost, so they apply unless you set them. `Infinity` turns one off. A limit that is reached stops the run with a LIMIT finding.
 
 Besides one XML token, the stack of open elements and the declarations of the part's internal subset, office-defuse holds the central directory's table of entries, which parts each part's relationships reach, and, while it reads a relationships part, the Ids that part has given so far, about 100 bytes each, so it can find one given twice. Content types, manifest paths and object references that name no entry of the archive are not kept. Everything else streams.
 
@@ -198,16 +279,22 @@ A finding's `category` and `detail` are plain strings, and `weight`, when set, s
 
 ## What it does not check
 
-- The contents of OLE files, such as VBA source, the objects inside `oleObject*.bin`, and ActiveX binaries.
-- Images, fonts and other media in a package, and the inside of an embedded Office package such as a chart's workbook.
-- Formulas in .xlsb sheets, and Excel functions other than DDE that reach outside, such as WEBSERVICE, RTD and IMAGE. Data connections in `connections.xml`.
+- The OLE parts of a ZIP package, such as `vbaProject.bin`, the objects inside `oleObject*.bin`, and ActiveX binaries.
+- VBA source. A VBA project is reported whole, and its modules go unread.
+- Encrypted .doc and .ppt files, and Excel's XOR obfuscation. They are rejected.
+- Formulas in .xls and .xlsb sheets. A DDE link that a formula uses is found in the workbook's link records.
+- Visio .vsd ShapeSheet cells, and anything in Publisher and Project files but VBA projects and objects.
+- An Outlook message's body, its RTF body included, and what an attached file holds.
+- The piece table of a Word 6.0 or 95 document. Its text is read in the order it is stored between the FIB's bounds, as msodde reads it, so a field that fast save split into pieces stored apart may not read whole.
+- Images, fonts and other media, and the inside of an embedded Office package such as a chart's workbook.
+- Excel functions other than DDE that reach outside, such as WEBSERVICE, RTD and IMAGE. Data connections in `connections.xml`.
 - OpenDocument form submit targets, Word's hyperlink base, and whether a link's visible text names a different site than its target.
 - Flat OpenDocument files such as `.fodt`, Flat OPC, and XPS. Inspect rejects them as not a ZIP archive or not a recognized package.
 - Bugs in an application's parsers that ordinary content can trigger.
 
 ## Development
 
-Development needs Node 22.12 or later. mocha 12 requires it, and the CommonJS test build loads chai 6, an ES module, with `require()`, which Node 22 supports only from 22.12. The pre-commit hook needs Node 22.22.1 or later for lint-staged. The tests also run `python3` and `unzip` to read the ZIP writer's output. The published package has no runtime dependencies and runs on any Node 22.
+Development needs Node 22.12 or later. mocha 12 requires it, and the CommonJS test build loads chai 6, an ES module, with `require()`, which Node 22 supports only from 22.12. The pre-commit hook needs Node 22.22.1 or later for lint-staged. The tests also run `python3` and `unzip` to read the ZIP writer's output. The published package has no runtime dependencies and runs on Node 18 or later.
 
 ```sh
 npm install --ignore-scripts
@@ -222,9 +309,9 @@ npm run format
 
 `npx husky` activates the pre-commit hook. A plain `npm install` does the same through the `prepare` script. The hook runs Biome on the staged files, applying its safe fixes, then runs `npm audit`. The commit stops if either one fails.
 
-The fixtures under `test/fixtures` are committed. `python3 -I scripts/make-fixtures.py` rebuilds them, and needs LibreOffice's `soffice`, Python 3 and Info-ZIP's `zip`. It converts flat OpenDocument sources with LibreOffice, adds macros, fields, relationships, objects and controls with Python's `zipfile`, and builds the hostile archives byte by byte.
+The fixtures under `test/fixtures` are committed. `python3 -I scripts/make-fixtures.py` rebuilds them, and needs LibreOffice's `soffice`, Python 3 and Info-ZIP's `zip`. It converts flat OpenDocument sources with LibreOffice, which also saves .doc, .xls, .ppt and .rtf versions of some of them. It adds macros, fields, relationships, objects and controls with Python's `zipfile`, and builds the hostile archives byte by byte. Compound files, RTF, Outlook messages and encrypted files come from its own compound file writer, AES and RC4. Two runs write the same bytes: the script sets `SAL_RAND_REPEATABLE` for LibreOffice, and fixes the timestamps and random ids LibreOffice writes.
 
-`test/fixtures/cases` holds one small package for each behavior a run over a corpus of real Office files turned up, written from scratch by `python3 -I scripts/make-fixtures.py cases`, which needs only Python. No corpus file, file name or path is in the repository, macro and OLE payloads are inert markers, and every address uses a reserved name. `manifest.json` gives each file's issue, what office-defuse reports for it, and what the build before the fix it documents reported. A test checks every entry, and that the manifest and the folder list the same files.
+`test/fixtures/cases` holds one small file for each behavior a run over a corpus of real Office files turned up, written from scratch by `python3 -I scripts/make-fixtures.py cases`, which needs only Python. No corpus file, file name or path is in the repository, macro and OLE payloads are inert markers, and every address uses a reserved name. `manifest.json` gives each file's issue, what office-defuse reports for it, and what the build before the fix it documents reported. A test checks every entry, and that the manifest and the folder list the same files.
 
 ## License
 

package/dist/biff.d.ts

@@ -0,0 +1,62 @@
+import type { CfbEntry, CompoundFile } from './cfb';
+/** Record types this reader acts on (MS-XLS 2.3). */
+export declare const R: {
+    bof: number;
+    eof: number;
+    filePass: number;
+    continue: number;
+    lbl: number;
+    externName: number;
+    boundSheet: number;
+    template: number;
+    addIn: number;
+    supBook: number;
+    externSheet: number;
+    obj: number;
+    hlink: number;
+};
+export interface BiffRecord {
+    type: number;
+    /** Where the record header starts in the stream. */
+    offset: number;
+    body: Uint8Array;
+}
+/** A sheet as BoundSheet8 (or BIFF5's BOUNDSHEET) lists it. */
+export interface Sheet {
+    position: number;
+    /** 0 visible, 1 hidden, 2 very hidden. */
+    state: number;
+    /** 0 worksheet or dialog, 1 macro sheet, 2 chart, 6 VBA module. */
+    type: number;
+    name: string;
+}
+/**
+ * Reads the records of a workbook stream one at a time, from `start` to the end of the stream. A record's body may
+ * run past the stream's end only by being cut short, which stops the reading as Excel stops.
+ */
+export declare class RecordReader {
+    readonly stream: CfbEntry;
+    private readonly deadline?;
+    private readonly reader;
+    private pos;
+    constructor(cfb: CompoundFile, stream: CfbEntry, start: number, deadline?: number | undefined);
+    next(): Promise<BiffRecord | undefined>;
+}
+/** BIFF8 writes strings with a flag byte: 8-bit characters, or 16-bit ones when its low bit is set. */
+export declare function xlString(b: Uint8Array, at: number, chars: number): {
+    text: string;
+    next: number;
+};
+/** A BoundSheet record, in BIFF8 or BIFF5. */
+export declare function parseBoundSheet(body: Uint8Array, biff8: boolean): Sheet;
+/** A defined name, in BIFF8 or BIFF5, with a built-in name spelled out. */
+export declare function parseLbl(body: Uint8Array, biff8: boolean): {
+    name: string;
+    builtin: boolean;
+    hidden: boolean;
+};
+/** The event a defined name runs a macro on, when Excel runs it on one: any name that starts with Auto_Open and so on. */
+export declare function autoName(name: string): {
+    event: string;
+    onOpen: boolean;
+} | undefined;

package/dist/biff.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RecordReader = exports.R = void 0;
+exports.xlString = xlString;
+exports.parseBoundSheet = parseBoundSheet;
+exports.parseLbl = parseLbl;
+exports.autoName = autoName;
+const errors_1 = require("./errors");
+const io_1 = require("./io");
+const oleobj_1 = require("./oleobj");
+/** Record types this reader acts on (MS-XLS 2.3). */
+exports.R = {
+    bof: 0x0809,
+    eof: 0x000a,
+    filePass: 0x002f,
+    continue: 0x003c,
+    lbl: 0x0018,
+    externName: 0x0023,
+    boundSheet: 0x0085,
+    template: 0x0060,
+    addIn: 0x0087,
+    supBook: 0x01ae,
+    externSheet: 0x0017,
+    obj: 0x005d,
+    hlink: 0x01b8,
+};
+/**
+ * Reads the records of a workbook stream one at a time, from `start` to the end of the stream. A record's body may
+ * run past the stream's end only by being cut short, which stops the reading as Excel stops.
+ */
+class RecordReader {
+    stream;
+    deadline;
+    reader;
+    pos;
+    constructor(cfb, stream, start, deadline) {
+        this.stream = stream;
+        this.deadline = deadline;
+        this.reader = new io_1.Reader(cfb.source(stream), stream.size, 16384, 8);
+        this.pos = start;
+    }
+    async next() {
+        if (this.pos + 4 > this.stream.size)
+            return undefined;
+        const h = await this.reader.read(this.pos, 4);
+        const type = h[0] | (h[1] << 8);
+        const length = h[2] | (h[3] << 8);
+        if (this.pos + 4 + length > this.stream.size)
+            return undefined;
+        const offset = this.pos;
+        const body = await this.reader.read(this.pos + 4, length);
+        this.pos += 4 + length;
+        if ((offset & 0xffff) < 4)
+            (0, errors_1.checkTime)(this.deadline);
+        return { type, offset, body };
+    }
+}
+exports.RecordReader = RecordReader;
+/** BIFF8 writes strings with a flag byte: 8-bit characters, or 16-bit ones when its low bit is set. */
+function xlString(b, at, chars) {
+    if (at >= b.length)
+        return { text: '', next: at };
+    const wide = (b[at] & 1) === 1;
+    const start = at + 1;
+    const end = Math.min(b.length, start + chars * (wide ? 2 : 1));
+    return { text: wide ? (0, oleobj_1.utf16)(b.subarray(start, end)) : (0, oleobj_1.latin1)(b.subarray(start, end)), next: end };
+}
+/** A BoundSheet record, in BIFF8 or BIFF5. */
+function parseBoundSheet(body, biff8) {
+    const position = (body[0] | (body[1] << 8) | (body[2] << 16) | (body[3] << 24)) >>> 0;
+    const state = body[4] & 3;
+    const type = body[5];
+    const cch = body[6] ?? 0;
+    const name = biff8 ? xlString(body, 7, cch).text : (0, oleobj_1.latin1)(body.subarray(7, 7 + cch));
+    return { position, state, type, name };
+}
+/** Built-in names Excel runs as macros (MS-XLS 2.5.112): Auto_Open and Auto_Activate as the workbook opens, Auto_Close and Auto_Deactivate as it closes. */
+const BUILTIN_NAMES = { 1: 'Auto_Open', 2: 'Auto_Close', 10: 'Auto_Activate', 11: 'Auto_Deactivate' };
+/** A defined name, in BIFF8 or BIFF5, with a built-in name spelled out. */
+function parseLbl(body, biff8) {
+    const flags = body[0] | (body[1] << 8);
+    const cch = body[3] ?? 0;
+    const builtin = (flags & 0x20) !== 0;
+    const name = biff8 ? xlString(body, 14, cch).text : (0, oleobj_1.latin1)(body.subarray(14, 14 + cch));
+    const shown = builtin && name.length > 0 ? (BUILTIN_NAMES[name.charCodeAt(0)] ?? `built-in name ${name.charCodeAt(0)}`) : name;
+    return { name: shown, builtin, hidden: (flags & 1) !== 0 };
+}
+/** The event a defined name runs a macro on, when Excel runs it on one: any name that starts with Auto_Open and so on. */
+function autoName(name) {
+    const m = /^(?:_xlnm\.)?(auto_open|auto_close|auto_activate|auto_deactivate)/i.exec(name);
+    if (!m)
+        return undefined;
+    const event = m[1].toLowerCase();
+    return { event: `${event[0].toUpperCase()}${event.slice(1, 5)}${event[5].toUpperCase()}${event.slice(6)}`, onOpen: event === 'auto_open' || event === 'auto_activate' };
+}

package/dist/cfb.d.ts

@@ -0,0 +1,58 @@
+import { type ByteSource, OfficeDetail as D } from './types';
+/** The first eight bytes of every compound file. */
+export declare const CFB_SIGNATURE: Uint8Array<ArrayBuffer>;
+export interface CfbLimits {
+    entries: number;
+    decompressedBytes: number;
+    totalDecompressedBytes: number;
+}
+export interface CfbEntry {
+    /** The entry's position in the directory. */
+    id: number;
+    name: string;
+    kind: 'root' | 'storage' | 'stream';
+    /** The class id, as Windows writes a GUID, in upper case. */
+    clsid: string;
+    size: number;
+    parent?: CfbEntry;
+    children: CfbEntry[];
+}
+/** Something the reader saw that it does not refuse. Each is a strip finding, since a rewrite leaves the bytes out. */
+export interface CfbNote {
+    detail: D.HiddenData | D.TrailingBytes;
+    bytes: number;
+}
+/** A GUID as Windows shows it: the first three fields little-endian, upper case, without braces. */
+export declare function guid(b: Uint8Array, at?: number): string;
+/** An entry name with control and format characters written as \xNN, so a location can show it. */
+export declare const showName: (name: string) => string;
+/** The entry's path from the root, its names joined by "/", which no name may hold. */
+export declare function entryPath(e: CfbEntry): string;
+/**
+ * A compound file (MS-CFB), read from its header, its allocation tables and its directory. Every chain is followed as
+ * far as its stream needs and every sector has one owner, so two readers cannot read the file differently. Reading a
+ * stream maps its offsets through its chain; nothing is held but the tables.
+ */
+export declare class CompoundFile {
+    private readonly reader;
+    readonly sectorSize: number;
+    readonly root: CfbEntry;
+    /** Every entry the directory tree reaches, the root first, each storage before its children. */
+    readonly entries: CfbEntry[];
+    readonly notes: CfbNote[];
+    private readonly miniStream;
+    private readonly deadline;
+    private readonly streamChains;
+    private constructor();
+    /** The child of a storage with this name, compared ignoring case. */
+    child(storage: CfbEntry, name: string): CfbEntry | undefined;
+    /** Reads a compound file. The caller has seen its signature. */
+    static open(source: ByteSource, limits: CfbLimits, deadline?: number): Promise<CompoundFile>;
+    /** Bytes of the mini stream, by their offset in it. */
+    private readMini;
+    private readChain;
+    /** A random-access source over a stream's content. */
+    source(e: CfbEntry): ByteSource;
+    /** A stream's whole content. Callers read only streams whose size they bounded. */
+    bytes(e: CfbEntry): Promise<Uint8Array>;
+}