@patrickdk77/office-defuse 0.2.0 → 0.2.1

package/README.md

@@ -91,7 +91,7 @@ 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 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. Neither needs the password of an encrypted file. 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.
 
@@ -101,6 +101,19 @@ A file that starts as XML, after any byte order mark and white space, is a flat
 
 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.
 
+## Detection
+
+`detectOffice(bytes, options)` and `detectOfficeSource(source, options)` tell a router whether office-defuse reads a file. They return `{ mimeType, extension, offset }`, or undefined. `extension` and `mimeType` are the `format` and `mimeType` an inspection reports. The inspection and detection name a file with the same functions. Detection opens the container and reads only what names the format, without the rules, the plugins or the rewrite:
+
+- the streams at a compound file's root, and for Word and Excel the FIB or the workbook's globals, which say whether it is a template or an add-in
+- a package's `[Content_Types].xml` and package relationships, or its `mimetype` entry and manifest
+- a flat file's root element, and for Flat OPC each part's name and content type and the package relationships
+- the first bytes of RTF
+
+Detection does not claim a file whose format office-defuse cannot name. That covers a ZIP archive with no Office marker and a package of another kind, such as a NuGet package or a StarOffice file. It covers a compound file with no Office document at its root, such as an installer or a bare OLE object, and a file that is a ZIP archive and a compound file at once. An encrypted OOXML package names its format only once it is decrypted, and detection has no password. When VelvetSweatshop opens the package, detection names the format inside. Otherwise it claims the package as a compound file, application/x-ole-storage with an empty extension, since the file is office-defuse's whatever the password turns out to be. The inspection then decrypts it with the run's password, or rejects it as encrypted. Detection claims a file it can name even when the file is damaged further on, and the inspection then rejects it.
+
+`offset` is where the ZIP data starts in an archive with other data in front, as the ZIP reader finds it, and 0 for anything else. The name and declared type play no part, so `heuristic` is never set. `detectOfficeSource` leaves the source open and throws with the `DEFUSE_LIMIT` code once `options.deadline` passes. An I/O error from the source comes back unchanged. Naming a Flat OPC package packs its parts into a ZIP archive, which spills into `options.tempDir` past `options.memoryThreshold`. `officePlugin` accepts exactly what detection claims.
+
 ## What it reports
 
 In a ZIP package:
@@ -241,7 +254,7 @@ The findings a plugin returns go into the report with their `location` after the
 
 The plugin context has `depth`, the file's depth in the upload, and `deadline`, which every file of the upload shares. An error with `code: 'DEFUSE_LIMIT'` or `code: 'DEFUSE_IO'` from a plugin stops the whole upload. At depth 0, a limit becomes LIMIT/TIME or LIMIT/NESTING_DEPTH, and an I/O error is thrown as its cause.
 
-`officePlugin(options)` defuses Office and OpenDocument files inside other files. It accepts a file by its content alone: a compound file, RTF, a ZIP archive with `[Content_Types].xml`, a `mimetype` entry or `META-INF/manifest.xml`, or XML whose root is a flat OpenDocument document or a Flat OPC package. It runs disarm at the context's depth with the context's deadline. Without `options` it takes the options of the office-defuse run that found the file, or none when another package found it. A clean file comes back `passed`, a defused one `scrubbed`, both with the rewritten bytes, and a rejected one `removed`. The findings it returns carry their `weight`.
+`officePlugin(options)` defuses Office and OpenDocument files inside other files. It accepts the files [`detectOffice`](#detection) claims, by their content alone, an encrypted OOXML package included, which it decrypts with the run's password. It runs disarm at the context's depth with the context's deadline. Without `options` it takes the options of the office-defuse run that found the file, or none when another package found it. A clean file comes back `passed`, a defused one `scrubbed`, both with the rewritten bytes, and a rejected one `removed`. The findings it returns carry their `weight`.
 
 ```js
 const { disarmOffice, officePlugin } = require('@patrickdk77/office-defuse');

package/dist/detect.d.ts

@@ -0,0 +1,13 @@
+import { type ByteSource, type DetectOptions, type FormatDetection } from './types';
+/**
+ * The format office-defuse reads `source` as, when it can name it from the content: the format and MIME type an
+ * inspection reports, read the way the inspection reads them, without the rules, the plugins or the rewrite. A ZIP
+ * archive, compound file or XML file whose format it cannot name, such as a plain archive, an installer or a package
+ * of another kind, is not claimed. A file it names but cannot read past that point is claimed, and an inspection then
+ * rejects it. So is an encrypted Office Open XML package no password at hand opens, as application/x-ole-storage with
+ * no extension, since only the password says which format is inside. The offset is that of the ZIP data in an archive with data in front, and 0 otherwise. The name and the
+ * declared type play no part. The source stays open.
+ */
+export declare function detectOfficeSource(source: ByteSource, options?: DetectOptions): Promise<FormatDetection | undefined>;
+/** `detectOfficeSource` over bytes in memory. */
+export declare function detectOffice(bytes: Uint8Array, options?: DetectOptions): Promise<FormatDetection | undefined>;

package/dist/detect.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectOfficeSource = detectOfficeSource;
+exports.detectOffice = detectOffice;
+const engine_1 = require("./engine");
+const errors_1 = require("./errors");
+const flat_1 = require("./flat");
+const formats_1 = require("./formats");
+const io_1 = require("./io");
+const ole_1 = require("./ole");
+const package_1 = require("./package");
+const types_1 = require("./types");
+/**
+ * The format of a file whose container `openContainer` read, named by the steps the inspection names it by, without
+ * the rules: the root of a compound file, and for Word and Excel whether it is a template or an add-in; the markers,
+ * [Content_Types].xml and package relationships of a package; the root of a flat file; or RTF. An encrypted package
+ * names its format when the passwords the run tries, which without a password is VelvetSweatshop alone, open it.
+ */
+async function nameContainer(ctx, container, src, size, limits) {
+    if (container.kind === 'rtf')
+        return formats_1.RTF_FORMAT;
+    if (container.kind === 'xml')
+        return (0, flat_1.nameFlat)(ctx, src, size, limits);
+    if (container.kind === 'zip')
+        return (0, package_1.namePackage)(ctx.withZip(container.zip));
+    const cfb = container.cfb;
+    const family = (0, ole_1.mainFamily)(cfb);
+    const format = await (0, ole_1.compoundFormat)(cfb, family, ctx.settings.deadline);
+    if (format)
+        return format;
+    try {
+        return await (0, package_1.namePackage)(ctx.withZip(await (0, ole_1.openEncryptedPackage)(ctx, cfb)));
+    }
+    catch (e) {
+        // An encrypted package that no password at hand opens is still office-defuse's. Only the password says which
+        // format is inside, and the inspection decrypts it with the run's password or rejects it as encrypted.
+        if (family === 'encrypted' && e instanceof errors_1.StopError && e.category === types_1.OfficeCategory.Encrypted)
+            return ENCRYPTED_PACKAGE;
+        throw e;
+    }
+}
+/** An encrypted Office Open XML package whose format no password at hand reveals: a compound file, with no extension of its own. */
+const ENCRYPTED_PACKAGE = { format: '', mimeType: 'application/x-ole-storage' };
+/**
+ * The format office-defuse reads `source` as, when it can name it from the content: the format and MIME type an
+ * inspection reports, read the way the inspection reads them, without the rules, the plugins or the rewrite. A ZIP
+ * archive, compound file or XML file whose format it cannot name, such as a plain archive, an installer or a package
+ * of another kind, is not claimed. A file it names but cannot read past that point is claimed, and an inspection then
+ * rejects it. So is an encrypted Office Open XML package no password at hand opens, as application/x-ole-storage with
+ * no extension, since only the password says which format is inside. The offset is that of the ZIP data in an archive with data in front, and 0 otherwise. The name and the
+ * declared type play no part. The source stays open.
+ */
+async function detectOfficeSource(source, options = {}) {
+    const run = (0, engine_1.newRun)({ tempDir: options.tempDir, memoryThreshold: options.memoryThreshold }, 0, options.deadline);
+    const src = (0, engine_1.guarded)(source);
+    try {
+        const { limits, settings, ctx } = (0, engine_1.runContext)(run);
+        const size = await src.size();
+        (0, errors_1.checkTime)(run.deadline);
+        const container = await (0, engine_1.openContainer)(src, size, limits, settings);
+        const format = await nameContainer(ctx, container, src, size, limits);
+        if (run.temp.ioError !== undefined)
+            throw run.temp.ioError;
+        return { mimeType: format.mimeType, extension: format.format, offset: container.kind === 'zip' ? container.zip.start : 0 };
+    }
+    catch (e) {
+        if (src.failure !== undefined)
+            throw src.failure;
+        if (run.temp.ioError !== undefined)
+            throw run.temp.ioError;
+        if ((0, errors_1.stopsTree)(e) !== undefined || (0, errors_1.isIoError)(e))
+            throw e;
+        // Any other failure, as in an inspection, means office-defuse cannot name the file's format.
+        return undefined;
+    }
+    finally {
+        await (0, engine_1.endRun)(run);
+    }
+}
+/** `detectOfficeSource` over bytes in memory. */
+function detectOffice(bytes, options = {}) {
+    return detectOfficeSource((0, io_1.bufferSource)(bytes), options);
+}

package/dist/engine.d.ts

@@ -1,4 +1,57 @@
-import { type ByteSink, type ByteSource, type OfficeDisarmResult, type OfficeInspection, type OfficeOptions } from './types';
+import { CompoundFile } from './cfb';
+import { RunContext, type RunSettings, type RunState } from './context';
+import { type ByteSink, type ByteSource, type OfficeDisarmResult, type OfficeInspection, type OfficeLimits, type OfficeOptions } from './types';
+import { ZipArchive } from './zip';
+declare const DEFAULT_LIMITS: {
+    entries: number;
+    decompressedBytes: number;
+    totalDecompressedBytes: number;
+    xmlDepth: number;
+    xmlTokenSize: number;
+    xmlEntityDepth: number;
+    xmlEntityExpansions: number;
+    xmlEntitySize: number;
+    rtfDepth: number;
+};
+export type Limits = typeof DEFAULT_LIMITS & Pick<OfficeLimits, 'fileSize' | 'timeMs' | 'nestingDepth'>;
+/**
+ * Wraps the source for one run. A read that returns more or fewer bytes than the source's size allows fails with
+ * code EIO, since the reader would take the shifted bytes for the file. Any error the source throws is kept, and the
+ * engine throws it instead of a verdict on the file.
+ */
+export declare function guarded(source: ByteSource): ByteSource & {
+    failure?: unknown;
+};
+export type Container = {
+    kind: 'zip';
+    zip: ZipArchive;
+} | {
+    kind: 'cfb';
+    cfb: CompoundFile;
+} | {
+    kind: 'rtf';
+} | {
+    kind: 'xml';
+};
+/**
+ * Reads the file's container. A file that starts with the compound file signature is read as one, and one that
+ * starts with {\rt is RTF, which is how Word tells them. The ZIP reader runs too, from the end: a file both read is
+ * ambiguous, since Office goes by the first bytes and a ZIP reader by the last. A compound file that does not read is
+ * a ZIP archive with data in front, if the ZIP reader read one. Word reads any file that starts with {\rt as RTF, so
+ * that does not fail. A file that starts as XML is a flat OpenDocument file or a Flat OPC package, and one that is a
+ * ZIP archive as well is ambiguous.
+ */
+export declare function openContainer(src: ByteSource, size: number, limits: Limits, settings: RunSettings): Promise<Container>;
+/** A run of the engine over one file at `depth`, with the deadline the whole upload shares. */
+export declare function newRun(options: OfficeOptions, depth: number, deadline: number | undefined, verify?: RunState['verify']): RunState;
+/** Releases what a run holds: the copies plugins returned and the temporary directory. */
+export declare function endRun(run: RunState): Promise<void>;
+/** The limits, settings and context a run reads its file with, from the run's options. */
+export declare function runContext(run: RunState): {
+    limits: Limits;
+    settings: RunSettings;
+    ctx: RunContext;
+};
 /** Inspects an Office or OpenDocument file without changing it. The source is closed when the run ends. */
 export declare function inspectOfficeSource(source: ByteSource, options?: OfficeOptions): Promise<OfficeInspection>;
 /** Inspects Office or OpenDocument bytes. */
@@ -14,3 +67,4 @@ export declare function disarmAtDepth(source: ByteSource, sink: ByteSink, option
 export declare function disarmOffice(bytes: Uint8Array, options?: OfficeOptions): Promise<OfficeDisarmResult & {
     bytes?: Uint8Array;
 }>;
+export {};

package/dist/engine.js

@@ -1,5 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.guarded = guarded;
+exports.openContainer = openContainer;
+exports.newRun = newRun;
+exports.endRun = endRun;
+exports.runContext = runContext;
 exports.inspectOfficeSource = inspectOfficeSource;
 exports.inspectOffice = inspectOffice;
 exports.disarmOfficeSource = disarmOfficeSource;
@@ -178,6 +183,21 @@ async function endRun(run) {
         await run.temp.cleanup();
     }
 }
+/** The limits, settings and context a run reads its file with, from the run's options. */
+function runContext(run) {
+    const options = run.options;
+    const limits = resolveLimits(options.limits);
+    const password = options.password;
+    const settings = {
+        entries: limits.entries,
+        decompressedBytes: limits.decompressedBytes,
+        totalDecompressedBytes: limits.totalDecompressedBytes,
+        rtfDepth: limits.rtfDepth,
+        deadline: run.deadline,
+        passwords: typeof password === 'string' ? [password] : (password ?? []),
+    };
+    return { limits, settings, ctx: new context_1.RunContext(new findings_1.FindingFactory(options.actionOverrides), xmlLimitsOf(limits), settings, run) };
+}
 /** The finding a limit error from this package or any other gives at depth 0. */
 function limitFinding(factory, e) {
     return factory.make(types_1.OfficeCategory.Limit, e.limit === 'nesting' ? types_1.OfficeDetail.NestingDepth : types_1.OfficeDetail.Time);
@@ -188,21 +208,11 @@ function limitFinding(factory, e) {
  */
 async function analyze(run, source) {
     const options = run.options;
-    const limits = resolveLimits(options.limits);
     const deadline = run.deadline;
-    const factory = new findings_1.FindingFactory(options.actionOverrides);
+    const { limits, settings, ctx } = runContext(run);
+    const factory = ctx.factory;
     const findings = [];
     const src = guarded(source);
-    const password = options.password;
-    const settings = {
-        entries: limits.entries,
-        decompressedBytes: limits.decompressedBytes,
-        totalDecompressedBytes: limits.totalDecompressedBytes,
-        rtfDepth: limits.rtfDepth,
-        deadline,
-        passwords: typeof password === 'string' ? [password] : (password ?? []),
-    };
-    const ctx = new context_1.RunContext(factory, xmlLimitsOf(limits), settings, run);
     const isOutput = run.verify !== undefined;
     try {
         if (limits.nestingDepth !== undefined && run.depth > limits.nestingDepth)

package/dist/flat.d.ts

@@ -12,16 +12,16 @@ export declare const FLAT_ODF_PART = "office:document";
 export declare const FLAT_OPC_FORMAT: Format;
 /** Whether the first bytes of a file read as XML: a byte order mark, white space and then "<". */
 export declare function startsAsXml(head: Uint8Array): boolean;
-/**
- * Whether the start of an XML file names a flat OpenDocument document or a Flat OPC package as its root element. The
- * reading of the whole file decides; this tells a router which package to try.
- */
-export declare function isFlatHead(text: string): boolean;
 /**
  * Inspects a flat XML file: flat OpenDocument, read with the OpenDocument rules over its one part, or Flat OPC,
  * which is unpacked into a package of its parts and read with the OOXML rules. Returns what the rewrite needs.
  */
 export declare function inspectFlat(ctx: RunContext, src: ByteSource, size: number, zipLimits: ZipLimits): Promise<Output | undefined>;
+/**
+ * Names a flat file's format as its inspection does, without the rules: flat OpenDocument by its root element, and a
+ * Flat OPC package once the package its parts make names an OOXML format.
+ */
+export declare function nameFlat(ctx: RunContext, src: ByteSource, size: number, zipLimits: ZipLimits): Promise<Format>;
 /** Writes a flat OpenDocument file without what the plan removes. */
 export declare function writeFlatOdf(run: RunState, src: ByteSource, plan: PackagePlan, limits: XmlLimits, sink: ByteSink): Promise<void>;
 /**

package/dist/flat.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FLAT_OPC_FORMAT = exports.FLAT_ODF_PART = exports.PKG_NS = void 0;
 exports.startsAsXml = startsAsXml;
-exports.isFlatHead = isFlatHead;
 exports.inspectFlat = inspectFlat;
+exports.nameFlat = nameFlat;
 exports.writeFlatOdf = writeFlatOdf;
 exports.writeFlatOpc = writeFlatOpc;
 const node_util_1 = require("node:util");
@@ -51,16 +51,6 @@ function startsAsXml(head) {
     const text = new node_util_1.TextDecoder(found.encoding, { fatal: false }).decode(head.subarray(found.bom));
     return text.trimStart().startsWith('<');
 }
-/**
- * Whether the start of an XML file names a flat OpenDocument document or a Flat OPC package as its root element. The
- * reading of the whole file decides; this tells a router which package to try.
- */
-function isFlatHead(text) {
-    const body = text.replace(/^\uFEFF/, '').replace(/^(?:\s|<\?[\s\S]*?\?>|<!--[\s\S]*?-->|<!DOCTYPE[^>]*>)*/, '');
-    const qname = /^<([^\s/>]+)/.exec(body)?.[1] ?? '';
-    const local = qname.slice(qname.indexOf(':') + 1);
-    return (local === 'document' && /urn:oasis:names:tc:opendocument:xmlns:office:1\.\d/i.test(text)) || (local === 'package' && text.includes(exports.PKG_NS));
-}
 /** Decodes base64 that arrives in pieces of any size, white space and line ends included. */
 class Base64 {
     rest = '';
@@ -141,6 +131,7 @@ class FlatOdf {
 class FlatOpc {
     run;
     pending;
+    keep;
     parts = [];
     /** Where the pkg:package start tag begins, which is where the prolog ends. */
     rootStart = 0;
@@ -148,9 +139,12 @@ class FlatOpc {
     xmlDepth = 0;
     b64;
     scopes = [];
-    constructor(run, pending) {
+    constructor(run, pending, 
+    /** The parts whose content is kept, by name. The others keep only their name, content type and attributes. */
+    keep = () => true) {
         this.run = run;
         this.pending = pending;
+        this.keep = keep;
     }
     start(el) {
         this.scopes.push(el.namespaces);
@@ -182,7 +176,7 @@ class FlatOpc {
             this.part.xml = { start: el.end, end: el.end, inherited };
             this.xmlDepth = el.depth;
         }
-        else if (el.depth === 3 && this.part && el.local === 'binaryData') {
+        else if (el.depth === 3 && this.part && el.local === 'binaryData' && this.keep(this.part.name)) {
             const sink = new io_1.SpillSink(this.run.temp, this.run.threshold);
             this.run.held.push(sink);
             this.part.binary = sink;
@@ -210,6 +204,23 @@ class FlatOpc {
         }
     }
 }
+/**
+ * The format a flat file's root element names: a flat OpenDocument format by its office:mimetype, or 'opc' for a Flat
+ * OPC package, whose format the package its parts make names. Throws for any other root, or a flat OpenDocument media
+ * type this package does not read.
+ */
+function flatRoot(el) {
+    if ((0, odf_1.odfNamespace)(el.ns) === odf_1.NS.office && el.local === 'document') {
+        const type = (0, odf_1.oattr)(el, odf_1.NS.office, 'mimetype') ?? '';
+        const format = FLAT_ODF.get(type);
+        if (!format)
+            throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, 'The flat OpenDocument media type is not one this package reads', { mediaType: (0, context_1.clip)(type) });
+        return format;
+    }
+    if (el.ns === exports.PKG_NS && el.local === 'package')
+        return 'opc';
+    throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, 'The XML file is neither flat OpenDocument nor Flat OPC', { root: (0, context_1.clip)(el.qname), namespace: (0, context_1.clip)(el.ns) });
+}
 /** Reads the root element and hands everything to the rules of the flat format it names. */
 class FlatReader {
     ctx;
@@ -223,19 +234,14 @@ class FlatReader {
     }
     start(el) {
         if (el.depth === 1) {
-            if ((0, odf_1.odfNamespace)(el.ns) === odf_1.NS.office && el.local === 'document') {
-                const type = (0, odf_1.oattr)(el, odf_1.NS.office, 'mimetype') ?? '';
-                this.format = FLAT_ODF.get(type);
-                if (!this.format)
-                    throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, 'The flat OpenDocument media type is not one this package reads', { mediaType: (0, context_1.clip)(type) });
-                this.ctx.format = this.format;
-                this.odf = new FlatOdf(this.ctx, this.ctx.run, this.pending);
-            }
-            else if (el.ns === exports.PKG_NS && el.local === 'package') {
+            const format = flatRoot(el);
+            if (format === 'opc')
                 this.opc = new FlatOpc(this.ctx.run, this.pending);
+            else {
+                this.format = format;
+                this.ctx.format = format;
+                this.odf = new FlatOdf(this.ctx, this.ctx.run, this.pending);
             }
-            else
-                throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, 'The XML file is neither flat OpenDocument nor Flat OPC', { root: (0, context_1.clip)(el.qname), namespace: (0, context_1.clip)(el.ns) });
         }
         this.odf?.start(el);
         this.opc?.start(el);
@@ -350,7 +356,6 @@ function partXml(text, inherited) {
  * which is unpacked into a package of its parts and read with the OOXML rules. Returns what the rewrite needs.
  */
 async function inspectFlat(ctx, src, size, zipLimits) {
-    const run = ctx.run;
     const pctx = ctx.withPlan();
     const pending = new Pending();
     const reader = new FlatReader(pctx, pending);
@@ -366,7 +371,25 @@ async function inspectFlat(ctx, src, size, zipLimits) {
     const opc = reader.opc;
     if (!opc)
         return undefined;
-    const xmlParts = opc.parts.filter(p => p.xml);
+    const { zip, prolog } = await packFlatOpc(ctx, src, size, opc, zipLimits);
+    const zctx = ctx.withZip(zip);
+    const contentTypes = zip.get('[Content_Types].xml');
+    if (!contentTypes)
+        return undefined;
+    const inner = await (0, ooxml_1.inspectOoxml)(zctx, contentTypes, exports.FLAT_OPC_FORMAT);
+    const layout = {
+        instructions: [...prolog.matchAll(/<\?mso-application\s[^?]*\?>/g)].map(m => m[0]),
+        extra: new Map(opc.parts.map(p => [(0, zip_1.nameKey)(p.name), p.extra])),
+    };
+    return { kind: 'flatopc', zip, plan: zctx.plan, format: inner, layout };
+}
+/**
+ * Packs the parts of a Flat OPC package into a ZIP archive, with a [Content_Types].xml that gives each its content
+ * type, and returns it with the text before the package element. A part the reader did not keep goes in empty.
+ */
+async function packFlatOpc(ctx, src, size, opc, zipLimits) {
+    const run = ctx.run;
+    const xmlParts = opc.parts.filter(p => p.xml && opc.keep(p.name));
     const cut = await cutText(src, size, ctx.settings.deadline, opc.rootStart, xmlParts.map(p => p.xml ?? { start: 0, end: 0 }));
     // The parts go into a package of their own, with a [Content_Types].xml that gives each its content type.
     const packed = new io_1.SpillSink(run.temp, run.threshold);
@@ -384,8 +407,9 @@ async function inspectFlat(ctx, src, size, zipLimits) {
     for (const p of opc.parts) {
         (0, errors_1.checkTime)(ctx.settings.deadline);
         let data = new Uint8Array(0);
-        if (p.xml)
-            data = partXml(cut.texts[xmlParts.indexOf(p)], p.xml.inherited);
+        const cutAt = xmlParts.indexOf(p);
+        if (p.xml && cutAt >= 0)
+            data = partXml(cut.texts[cutAt], p.xml.inherited);
         else if (p.binary) {
             const chunks = [];
             for await (const c of p.binary.read())
@@ -398,21 +422,66 @@ async function inspectFlat(ctx, src, size, zipLimits) {
     await packed.close();
     const packedSource = packed.source();
     run.sources.push(packedSource);
-    const zip = await zip_1.ZipArchive.open(packedSource, zipLimits, ctx.settings.deadline);
-    const zctx = ctx.withZip(zip);
+    return { zip: await zip_1.ZipArchive.open(packedSource, zipLimits, ctx.settings.deadline), prolog: cut.prolog };
+}
+/** Stops the reading of a flat file once its root has named a flat OpenDocument format. */
+const ROOT_NAMED = new Error('The root names the format');
+/**
+ * Reads a flat file as far as naming its format needs: its root element, and for a Flat OPC package, every part's
+ * name, content type and attributes, with the content of the package relationships alone.
+ */
+class FlatNamer {
+    run;
+    pending;
+    format;
+    opc;
+    constructor(run, pending) {
+        this.run = run;
+        this.pending = pending;
+    }
+    start(el) {
+        if (el.depth === 1) {
+            const format = flatRoot(el);
+            if (format !== 'opc') {
+                this.format = format;
+                throw ROOT_NAMED;
+            }
+            this.opc = new FlatOpc(this.run, this.pending, name => (0, ooxml_1.relsSource)(name) === '');
+        }
+        this.opc?.start(el);
+    }
+    text(t) {
+        this.opc?.text(t);
+    }
+    end(el, start) {
+        this.opc?.end(el, start);
+    }
+}
+/**
+ * Names a flat file's format as its inspection does, without the rules: flat OpenDocument by its root element, and a
+ * Flat OPC package once the package its parts make names an OOXML format.
+ */
+async function nameFlat(ctx, src, size, zipLimits) {
+    const pending = new Pending();
+    const namer = new FlatNamer(ctx.run, pending);
+    try {
+        await ctx.parseXml(FLAT_OPC_PART, chunksOf(src, size, ctx.settings.deadline), namer, false, undefined, () => pending.flush());
+    }
+    catch (e) {
+        if (e !== ROOT_NAMED)
+            throw e;
+    }
+    if (namer.format)
+        return namer.format;
+    const opc = namer.opc;
+    if (!opc)
+        throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, 'The XML file has no root element', { reason: 'no root element' });
+    const { zip } = await packFlatOpc(ctx, src, size, opc, zipLimits);
     const contentTypes = zip.get('[Content_Types].xml');
     if (!contentTypes)
-        return undefined;
-    await (0, ooxml_1.inspectOoxml)(zctx, contentTypes);
-    const inner = ctx.format;
-    ctx.format = exports.FLAT_OPC_FORMAT;
-    if (!inner)
-        return undefined;
-    const layout = {
-        instructions: [...cut.prolog.matchAll(/<\?mso-application\s[^?]*\?>/g)].map(m => m[0]),
-        extra: new Map(opc.parts.map(p => [(0, zip_1.nameKey)(p.name), p.extra])),
-    };
-    return { kind: 'flatopc', zip, plan: zctx.plan, format: inner, layout };
+        throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, 'The Flat OPC package has no [Content_Types].xml', { reason: 'no [Content_Types].xml' });
+    await (0, ooxml_1.nameOoxml)(ctx.withZip(zip), contentTypes);
+    return exports.FLAT_OPC_FORMAT;
 }
 /** Writes a flat OpenDocument file without what the plan removes. */
 async function writeFlatOdf(run, src, plan, limits, sink) {

package/dist/formats.d.ts

@@ -15,3 +15,5 @@ export declare const XPS_FORMATS: {
 };
 /** OpenDocument formats by the media type in the mimetype entry or the manifest, exactly as written. */
 export declare const ODF_FORMATS: Map<string, Format>;
+/** RTF, which Word reads in any file that starts with {\rt. */
+export declare const RTF_FORMAT: Format;

package/dist/formats.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ODF_FORMATS = exports.XPS_FORMATS = exports.XPS_SEQUENCE = exports.OOXML_FORMATS = void 0;
+exports.RTF_FORMAT = exports.ODF_FORMATS = exports.XPS_FORMATS = exports.XPS_SEQUENCE = exports.OOXML_FORMATS = void 0;
 const f = (format, mimeType) => ({ format, mimeType });
 /** OOXML formats by the content type of the main part, lowercased. */
 exports.OOXML_FORMATS = new Map([
@@ -48,3 +48,5 @@ exports.ODF_FORMATS = new Map([
     ['text-master', 'odm'],
     ['base', 'odb'],
 ].map(([kind, ext]) => [`application/vnd.oasis.opendocument.${kind}`, f(ext, `application/vnd.oasis.opendocument.${kind}`)]));
+/** RTF, which Word reads in any file that starts with {\rt. */
+exports.RTF_FORMAT = f('rtf', 'application/rtf');

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export { detectOffice, detectOfficeSource } from './detect';
 export { disarmOffice, disarmOfficeSource, inspectOffice, inspectOfficeSource } from './engine';
 export { allFindingSpecs } from './findings';
 export { bufferSink, bufferSource, fileSink, fileSource, writableSink } from './io';

package/dist/index.js

@@ -14,7 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.scoreFindings = exports.DEFAULT_BANDS = exports.COMBINATIONS = exports.officePlugin = exports.writableSink = exports.fileSource = exports.fileSink = exports.bufferSource = exports.bufferSink = exports.allFindingSpecs = exports.inspectOfficeSource = exports.inspectOffice = exports.disarmOfficeSource = exports.disarmOffice = void 0;
+exports.scoreFindings = exports.DEFAULT_BANDS = exports.COMBINATIONS = exports.officePlugin = exports.writableSink = exports.fileSource = exports.fileSink = exports.bufferSource = exports.bufferSink = exports.allFindingSpecs = exports.inspectOfficeSource = exports.inspectOffice = exports.disarmOfficeSource = exports.disarmOffice = exports.detectOfficeSource = exports.detectOffice = void 0;
+var detect_1 = require("./detect");
+Object.defineProperty(exports, "detectOffice", { enumerable: true, get: function () { return detect_1.detectOffice; } });
+Object.defineProperty(exports, "detectOfficeSource", { enumerable: true, get: function () { return detect_1.detectOfficeSource; } });
 var engine_1 = require("./engine");
 Object.defineProperty(exports, "disarmOffice", { enumerable: true, get: function () { return engine_1.disarmOffice; } });
 Object.defineProperty(exports, "disarmOfficeSource", { enumerable: true, get: function () { return engine_1.disarmOfficeSource; } });

package/dist/index.mjs

@@ -1,3 +1,3 @@
 import cjs from './index.js';
-export const { disarmOffice, disarmOfficeSource, inspectOffice, inspectOfficeSource, allFindingSpecs, bufferSink, bufferSource, fileSink, fileSource, writableSink, officePlugin, COMBINATIONS, DEFAULT_BANDS, scoreFindings, OfficeCategory, OfficeDetail, OfficeRisk } = cjs;
+export const { detectOffice, detectOfficeSource, disarmOffice, disarmOfficeSource, inspectOffice, inspectOfficeSource, allFindingSpecs, bufferSink, bufferSource, fileSink, fileSource, writableSink, officePlugin, COMBINATIONS, DEFAULT_BANDS, scoreFindings, OfficeCategory, OfficeDetail, OfficeRisk } = cjs;
 export default cjs;

package/dist/odf.d.ts

@@ -1,6 +1,8 @@
 import { type PlanContext, type ZipContext } from './context';
+import { type Format } from './formats';
 import { OfficeCategory as C, OfficeDetail as D } from './types';
 import type { XmlElement, XmlHandler } from './xml';
+import { type ZipEntry } from './zip';
 export declare const NS: {
     manifest: string;
     office: string;
@@ -57,11 +59,31 @@ export declare class EntryRules implements XmlHandler {
     private scriptEvent;
     private presentationEvent;
 }
+export interface Manifest {
+    paths: Set<string>;
+    root?: string;
+    encrypted: boolean;
+}
 /** The code folder an entry sits in, as the folder's path and its finding. */
 export declare function folderOf(name: string): {
     prefix: string;
     detail: D;
     category: C;
 } | undefined;
+/** What names an OpenDocument package: the media type its format comes from, and the entries that give it. */
+export interface OdfNaming {
+    format: Format;
+    /** The media type the format was named by. */
+    mediaType: string;
+    mimetype?: ZipEntry;
+    manifestEntry?: ZipEntry;
+    manifest?: Manifest;
+}
+/**
+ * Names an OpenDocument package's format by the media type in its mimetype entry or, without one, its manifest's root
+ * entry. Throws when the two name different formats, or the media type is not one this package reads. `layout` hears,
+ * with the entry it concerns, of each way the mimetype entry and the manifest leave the layout OpenDocument asks for.
+ */
+export declare function nameOdf(ctx: ZipContext, layout?: (location: string, reason: string) => void): Promise<OdfNaming>;
 /** Inspects an OpenDocument package. */
 export declare function inspectOdf(ctx: ZipContext): Promise<void>;