@patrickdk77/office-defuse 0.1.1 → 0.2.0

package/dist/contained.d.ts

@@ -0,0 +1,46 @@
+import type { RunContext, RunState } from './context';
+import { SpillSink } from './io';
+import { type DefuseFinding, type OfficeOptions, type PluginContext } from './types';
+/** The key under which office-defuse hands its run's options to a plugin. No other package can name it. */
+export declare const RUN_OPTIONS: unique symbol;
+/** A plugin context as office-defuse makes it. */
+export type RunPluginContext = PluginContext & {
+    [RUN_OPTIONS]?: OfficeOptions;
+};
+/** What the plugins decided about a file inside the file. Undefined from `decideContained` means no plugin took it. */
+export interface ContainedDecision {
+    keep: boolean;
+    /** The bytes a plugin kept in place of the file's own. */
+    replacement?: SpillSink;
+}
+/** A file found inside the file, as the format rules hand it over. */
+export interface InnerFile {
+    name?: string;
+    /** The MIME type the container gives the file, such as a part's content type. */
+    declaredType?: string;
+    location: string;
+    /** The file's bytes, in order. */
+    chunks(): AsyncIterable<Uint8Array>;
+}
+/**
+ * Adds the findings a plugin reported from inside a file, labeled with the file's name and place. A reject inside the
+ * file means the file goes, not the one that holds it, so it is recorded here as strip.
+ */
+export declare function pushContained(ctx: RunContext, found: DefuseFinding[] | undefined, location: string, name: string | undefined): void;
+/**
+ * Shows a file found inside the file to the plugins, as pdf-defuse shows an attached file. The first plugin that
+ * accepts it decides: 'passed' and 'scrubbed' keep it, with the bytes the plugin wrote when it wrote any, and
+ * 'removed', a failure or a scrub that wrote nothing remove it. Its findings come into this run's report. When no
+ * plugin accepts the file, this returns undefined and the rules the file gets without plugins decide.
+ *
+ * In the run that checks an output, the plugins are not asked again. A file whose MD5 matches what a plugin kept in
+ * the upload's run is taken as kept, with the findings the plugin reported for its output.
+ */
+export declare function decideContained(ctx: RunContext, inner: InnerFile): Promise<ContainedDecision | undefined>;
+/**
+ * The rule a file gets for being there, such as EMBEDDED/OLE_OBJECT, applies when no plugin took the file. A plugin
+ * that kept the file turns those findings to info, since the content stays.
+ */
+export declare function presence(decision: ContainedDecision | undefined): 'info' | undefined;
+/** Bytes in a spill sink the run holds until it ends, as the rewrite takes a plugin's output. */
+export declare function spillOf(run: RunState, bytes: Uint8Array): Promise<SpillSink>;

package/dist/contained.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUN_OPTIONS = void 0;
+exports.pushContained = pushContained;
+exports.decideContained = decideContained;
+exports.presence = presence;
+exports.spillOf = spillOf;
+const errors_1 = require("./errors");
+const io_1 = require("./io");
+const sniff_1 = require("./sniff");
+const types_1 = require("./types");
+/** The key under which office-defuse hands its run's options to a plugin. No other package can name it. */
+exports.RUN_OPTIONS = Symbol('office-defuse run options');
+/**
+ * Throws on an error a plugin threw that stops the whole tree. An I/O error fails this run as one of its own would,
+ * so its cause goes up.
+ */
+function passOn(run, e) {
+    const code = (0, errors_1.stopsTree)(e);
+    if (code === 'DEFUSE_IO') {
+        const cause = e.cause ?? e;
+        run.temp.ioError ??= cause;
+        throw cause;
+    }
+    if (code === 'DEFUSE_LIMIT')
+        throw e;
+}
+/**
+ * Adds the findings a plugin reported from inside a file, labeled with the file's name and place. A reject inside the
+ * file means the file goes, not the one that holds it, so it is recorded here as strip.
+ */
+function pushContained(ctx, found, location, name) {
+    const label = name || 'unnamed file';
+    ctx.push((found ?? []).map(f => ({
+        ...f,
+        action: f.action === 'reject' ? 'strip' : f.action,
+        location: f.location ? `${location} > ${f.location}` : location,
+        data: f.data && { ...f.data },
+        attachment: f.attachment ? `${label} > ${f.attachment}` : label,
+    })));
+}
+/**
+ * Shows a file found inside the file to the plugins, as pdf-defuse shows an attached file. The first plugin that
+ * accepts it decides: 'passed' and 'scrubbed' keep it, with the bytes the plugin wrote when it wrote any, and
+ * 'removed', a failure or a scrub that wrote nothing remove it. Its findings come into this run's report. When no
+ * plugin accepts the file, this returns undefined and the rules the file gets without plugins decide.
+ *
+ * In the run that checks an output, the plugins are not asked again. A file whose MD5 matches what a plugin kept in
+ * the upload's run is taken as kept, with the findings the plugin reported for its output.
+ */
+async function decideContained(ctx, inner) {
+    const run = ctx.run;
+    const plugins = run.options.filePlugins ?? [];
+    if (!plugins.length && !run.verify?.size)
+        return undefined;
+    const decoded = new io_1.SpillSink(run.temp, run.threshold);
+    try {
+        for await (const c of inner.chunks())
+            await decoded.write(c);
+        await decoded.close();
+        const hash = decoded.digest();
+        const name = inner.name;
+        const expected = run.verify?.get(hash);
+        if (expected) {
+            ctx.report(types_1.OfficeCategory.Embedded, expected.result === 'passed' ? types_1.OfficeDetail.PluginPassed : types_1.OfficeDetail.PluginScrubbed, inner.location, { plugin: expected.plugin, name: name ?? '' });
+            pushContained(ctx, expected.findings, inner.location, name);
+            return { keep: true };
+        }
+        if (!plugins.length)
+            return undefined;
+        const source = decoded.source();
+        try {
+            const head = await source.read(0, Math.min(1024, decoded.length));
+            const file = { name, declaredType: inner.declaredType, sniffedType: (0, sniff_1.sniffType)(head), size: decoded.length, location: inner.location, depth: run.depth + 1, source };
+            const context = { depth: file.depth, deadline: run.deadline, [exports.RUN_OPTIONS]: run.options };
+            for (const plugin of plugins) {
+                try {
+                    if (!(await plugin.accepts(file)))
+                        continue;
+                }
+                catch (e) {
+                    passOn(run, e);
+                    continue;
+                }
+                // Copies a plugin keeps wait in memory until the rewrite, so all of them together stay under one threshold.
+                const out = new io_1.SpillSink(run.temp, Math.max(0, run.threshold - run.retained));
+                const data = { plugin: plugin.name, name: name ?? '' };
+                try {
+                    const answer = await plugin.process(file, out, context);
+                    const r = typeof answer === 'string' ? { result: answer } : (answer ?? {});
+                    await out.close();
+                    let keep = false;
+                    if (r.result === 'passed') {
+                        ctx.report(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.PluginPassed, inner.location, data);
+                        // Bytes the plugin wrote are the ones kept, such as a document rewritten with nothing removed. A container
+                        // the rewrite cannot change keeps the file as it was, which the plugin passed too.
+                        const passed = { result: 'passed', plugin: plugin.name, findings: r.outputFindings };
+                        run.kept.set(hash, passed);
+                        if (out.length > 0)
+                            run.kept.set(out.digest(), passed);
+                        keep = true;
+                    }
+                    else if (r.result === 'scrubbed' && out.length > 0) {
+                        ctx.report(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.PluginScrubbed, inner.location, data);
+                        run.kept.set(out.digest(), { result: 'scrubbed', plugin: plugin.name, findings: r.outputFindings });
+                        keep = true;
+                    }
+                    else
+                        ctx.removal(types_1.OfficeCategory.Embedded, r.result === 'removed' ? types_1.OfficeDetail.PluginRemoved : types_1.OfficeDetail.PluginFailed, inner.location, data);
+                    pushContained(ctx, r.findings, inner.location, name);
+                    const replacement = keep && out.length > 0 ? out : undefined;
+                    if (replacement) {
+                        if (!replacement.spilled)
+                            run.retained += replacement.length;
+                        run.held.push(replacement);
+                    }
+                    else
+                        await out.dispose();
+                    return { keep, replacement };
+                }
+                catch (e) {
+                    await out.dispose();
+                    passOn(run, e);
+                    ctx.removal(types_1.OfficeCategory.Embedded, types_1.OfficeDetail.PluginFailed, inner.location, data);
+                    return { keep: false };
+                }
+            }
+            return undefined;
+        }
+        finally {
+            await source.close?.();
+        }
+    }
+    finally {
+        await decoded.dispose();
+    }
+}
+/**
+ * The rule a file gets for being there, such as EMBEDDED/OLE_OBJECT, applies when no plugin took the file. A plugin
+ * that kept the file turns those findings to info, since the content stays.
+ */
+function presence(decision) {
+    return decision?.keep ? 'info' : undefined;
+}
+/** Bytes in a spill sink the run holds until it ends, as the rewrite takes a plugin's output. */
+async function spillOf(run, bytes) {
+    const sink = new io_1.SpillSink(run.temp, run.threshold);
+    run.held.push(sink);
+    await sink.write(bytes);
+    await sink.close();
+    return sink;
+}

package/dist/context.d.ts

@@ -1,6 +1,9 @@
+import type { CompoundFile } from './cfb';
 import type { FindingFactory } from './findings';
 import type { Format } from './formats';
-import { OfficeCategory as C, OfficeDetail as D, type DefuseFinding } from './types';
+import type { SpillSink, TempDir } from './io';
+import { type CompoundPlan, type FlatOpcLayout, PackagePlan, type RtfCut } from './plan';
+import { type ByteSource, OfficeCategory as C, OfficeDetail as D, type DefuseFinding, type OfficeFinding, type OfficeFindingAction, type OfficeOptions } from './types';
 import { type EntityBudget, type XmlHandler, type XmlLimits } from './xml';
 import type { ZipArchive, ZipEntry } from './zip';
 /** Cuts text from the file to a length that fits a finding's data. A reference to an external entity shows as `&name;`. */
@@ -13,8 +16,72 @@ export interface RunSettings {
     /** Group nesting in an RTF file, and destinations open at once. */
     rtfDepth: number;
     deadline?: number;
-    /** Tried first on an encrypted file, before the password the format opens with by default. */
-    password?: string;
+    /** Tried in order on an encrypted file, before the password the format opens with by default. */
+    passwords: readonly string[];
+}
+/** What a plugin returned for a file, which the output check expects to find again by the MD5 of its bytes. */
+export interface Expected {
+    result: 'passed' | 'scrubbed';
+    plugin: string;
+    findings?: DefuseFinding[];
+}
+/** What the rewrite starts from: the container the run read, and what its findings remove. */
+export type Output = {
+    kind: 'zip';
+    zip: ZipArchive;
+    plan: PackagePlan;
+    format: Format;
+} | {
+    kind: 'cfb';
+    cfb: CompoundFile;
+    plan: CompoundPlan;
+} | {
+    kind: 'rtf';
+    size: number;
+    cuts: RtfCut[];
+} | {
+    kind: 'flatodf';
+    plan: PackagePlan;
+}
+/** A Flat OPC package, unpacked into `zip`, whose OOXML format is `format`. */
+ | {
+    kind: 'flatopc';
+    zip: ZipArchive;
+    plan: PackagePlan;
+    format: Format;
+    layout: FlatOpcLayout;
+};
+/** What one run of the engine holds besides its findings: the caller's options, temporary files and plugin results. */
+export interface RunState {
+    options: OfficeOptions;
+    /** The depth of the file in the upload: 0 for the upload itself. */
+    depth: number;
+    deadline?: number;
+    temp: TempDir;
+    /** memoryThreshold, in bytes. */
+    threshold: number;
+    /** Bytes of plugin output held in memory until the rewrite. */
+    retained: number;
+    /** Set when the run checks an output: what the plugins returned for the upload's files. */
+    verify?: Map<string, Expected>;
+    /** What the plugins returned in this run, by the MD5 of the bytes kept. */
+    kept: Map<string, Expected>;
+    /** Plugin output that waits for the rewrite. The run disposes of it when it ends. */
+    held: SpillSink[];
+    /**
+     * Findings whose content a plugin kept, such as EMBEDDED/PACKAGE for a package a plugin passed. They stay in the
+     * report as info and leave the score to what the plugin found, as pdf-defuse leaves out a kept attached file.
+     */
+    superseded: WeakSet<DefuseFinding>;
+    /** Sources the rewrite reads from, such as a compound file a plugin returned, which the run closes when it ends. */
+    sources: ByteSource[];
+    /** The container, once the format rules have read it. */
+    output?: Output;
+}
+/** A finding the rules made, with its action, which the rewrite reads. Past 200 of one kind, `finding` is absent. */
+export interface Reported {
+    action: OfficeFindingAction;
+    finding?: OfficeFinding;
 }
 /** What every context of one inspection shares, so a package inside the file reports into the same list. */
 interface Shared {
@@ -24,6 +91,9 @@ interface Shared {
     /** Entity expansion in every part, which the entity limits bound. */
     budget: EntityBudget;
     format?: Format;
+    run: RunState;
+    /** Strip findings made so far, counted past the 200 kept of each kind too. */
+    strips: number;
 }
 /** What one inspection holds while the format rules run. */
 export declare class RunContext {
@@ -31,33 +101,58 @@ export declare class RunContext {
     readonly xmlLimits: XmlLimits;
     readonly settings: RunSettings;
     protected readonly shared: Shared;
-    constructor(factory: FindingFactory, xmlLimits: XmlLimits, settings: RunSettings, shared?: Shared);
+    constructor(factory: FindingFactory, xmlLimits: XmlLimits, settings: RunSettings, shared: Shared | RunState);
     get findings(): DefuseFinding[];
+    get run(): RunState;
+    /** How many strip findings the run has made, so a rule can tell whether anything it read made one. */
+    get strips(): number;
     /** Set as soon as the rules know it, so a run that stops later still names the format. */
     get format(): Format | undefined;
     set format(f: Format | undefined);
-    /** A context for a ZIP archive the rules read, reporting into the same findings. */
+    /** A context for a ZIP archive the rules read, reporting into the same findings, with a plan of its own. */
     withZip(zip: ZipArchive): ZipContext;
-    /** Records a finding. Past 200 of one kind, as in pdf-defuse, one more finding counts the rest. */
-    report(category: C, detail: D, location?: string, data?: Record<string, string | number>): void;
+    /** A context for rules that fill in a plan of their own without an archive, as for a flat XML file. */
+    withPlan(): PlanContext;
+    /**
+     * Records a finding. Past 200 of one kind, as in pdf-defuse, one more finding counts the rest. `action` replaces the
+     * action the overrides give, for content whose fate a plugin decided.
+     */
+    report(category: C, detail: D, location?: string, data?: Record<string, string | number>, action?: OfficeFindingAction): Reported;
+    /** Reports content that goes whatever the overrides say: its action is strip, or reject when the caller asked for that. */
+    removal(category: C, detail: D, location?: string, data?: Record<string, string | number>): Reported;
+    /** Adds findings from another package as they are, such as those a plugin made inside a file. */
+    push(findings: DefuseFinding[]): void;
     /** Reports a link, classified by pdf-defuse's checks of its target. */
-    link(target: string, location: string, data?: Record<string, string>): void;
+    link(target: string, location: string, data?: Record<string, string>): Reported;
+    /**
+     * Reports a safe link whose text or tooltip names another site than the one it opens, as LINK/TEXT_MISMATCH. Returns
+     * undefined when no label names a site, or every site a label names is the target's.
+     */
+    labelMismatch(target: string, labels: ReadonlyArray<string | undefined>, location: string, data?: Record<string, string>): Reported | undefined;
     /**
      * Reports a reference that loads from outside the file on its own. It is EXTERNAL/LOCAL_FILE, with `kind` saying
      * what refers, when the target is on this machine, and `detail` otherwise.
      */
-    external(detail: D, target: string, location: string, data: Record<string, string>, kind: string): void;
+    external(detail: D, target: string, location: string, data: Record<string, string>, kind: string): Reported;
     /**
      * Tokenizes XML text, or Office's VML dialect, handing the events to `handler`. A document type declaration is
      * XML/DOCTYPE without an internal subset and XML/INTERNAL_SUBSET with one. A reference to an external entity in
      * content is XML/EXTERNAL_ENTITY.
      */
-    parseXml(part: string, chunks: AsyncIterable<Uint8Array> | Iterable<Uint8Array>, handler: XmlHandler, vml?: boolean): Promise<void>;
+    parseXml(part: string, chunks: AsyncIterable<Uint8Array> | Iterable<Uint8Array>, handler: XmlHandler, vml?: boolean, plan?: PackagePlan, after?: () => Promise<void>): Promise<void>;
+}
+/** The context of rules that fill in a rewrite plan: a ZIP package's, or a flat XML file's. */
+export declare class PlanContext extends RunContext {
+    /** What the rewrite removes, which the rules fill in as they report. */
+    readonly plan: PackagePlan;
+    constructor(
+    /** What the rewrite removes, which the rules fill in as they report. */
+    plan: PackagePlan, factory: FindingFactory, xmlLimits: XmlLimits, settings: RunSettings, shared: Shared);
 }
 /** The context of the rules that read a ZIP archive. */
-export declare class ZipContext extends RunContext {
+export declare class ZipContext extends PlanContext {
     readonly zip: ZipArchive;
-    constructor(zip: ZipArchive, factory: FindingFactory, xmlLimits: XmlLimits, settings: RunSettings, shared: Shared);
+    constructor(zip: ZipArchive, plan: PackagePlan, factory: FindingFactory, xmlLimits: XmlLimits, settings: RunSettings, shared: Shared);
     /** Inflates an entry and tokenizes it as XML, or as Office's VML dialect, handing the events to `handler`. */
     parse(entry: ZipEntry, handler: XmlHandler, vml?: boolean): Promise<void>;
     /** Inflates an entry, which checks it, hands each chunk to `visit`, and tells whether its bytes are an OLE file. */

package/dist/context.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ZipContext = exports.RunContext = exports.clip = void 0;
+exports.ZipContext = exports.PlanContext = exports.RunContext = exports.clip = void 0;
 const links_1 = require("./links");
+const plan_1 = require("./plan");
 const types_1 = require("./types");
 const xml_1 = require("./xml");
 const OLE_SIGNATURE = [0xd0, 0xcf, 0x11, 0xe0, 0xa1, 0xb1, 0x1a, 0xe1];
@@ -21,11 +22,18 @@ class RunContext {
         this.factory = factory;
         this.xmlLimits = xmlLimits;
         this.settings = settings;
-        this.shared = shared ?? { findings: [], perKind: new Map(), overflow: new Map(), budget: { expansions: 0, size: 0 } };
+        this.shared = 'run' in shared ? shared : { findings: [], perKind: new Map(), overflow: new Map(), budget: { expansions: 0, size: 0 }, run: shared, strips: 0 };
     }
     get findings() {
         return this.shared.findings;
     }
+    get run() {
+        return this.shared.run;
+    }
+    /** How many strip findings the run has made, so a rule can tell whether anything it read made one. */
+    get strips() {
+        return this.shared.strips;
+    }
     /** Set as soon as the rules know it, so a run that stops later still names the format. */
     get format() {
         return this.shared.format;
@@ -33,32 +41,71 @@ class RunContext {
     set format(f) {
         this.shared.format = f;
     }
-    /** A context for a ZIP archive the rules read, reporting into the same findings. */
+    /** A context for a ZIP archive the rules read, reporting into the same findings, with a plan of its own. */
     withZip(zip) {
-        return new ZipContext(zip, this.factory, this.xmlLimits, this.settings, this.shared);
+        return new ZipContext(zip, new plan_1.PackagePlan(), this.factory, this.xmlLimits, this.settings, this.shared);
+    }
+    /** A context for rules that fill in a plan of their own without an archive, as for a flat XML file. */
+    withPlan() {
+        return new PlanContext(new plan_1.PackagePlan(), this.factory, this.xmlLimits, this.settings, this.shared);
     }
-    /** Records a finding. Past 200 of one kind, as in pdf-defuse, one more finding counts the rest. */
-    report(category, detail, location, data) {
-        const k = `${category}/${detail}`;
+    /**
+     * Records a finding. Past 200 of one kind, as in pdf-defuse, one more finding counts the rest. `action` replaces the
+     * action the overrides give, for content whose fate a plugin decided.
+     */
+    report(category, detail, location, data, action) {
+        const act = action ?? this.factory.actionFor(category, detail);
+        if (act === 'strip')
+            this.shared.strips++;
+        const k = `${category}/${detail}/${act}`;
         const n = (this.shared.perKind.get(k) ?? 0) + 1;
         this.shared.perKind.set(k, n);
         if (n <= 200) {
-            this.shared.findings.push(this.factory.make(category, detail, location, data));
-            return;
+            const finding = this.factory.make(category, detail, location, data);
+            finding.action = act;
+            if (action === 'info')
+                this.run.superseded.add(finding);
+            this.shared.findings.push(finding);
+            return { action: act, finding };
         }
         let counted = this.shared.overflow.get(k);
         if (!counted) {
             // The first overflow fills the description's placeholders.
             counted = { ...data, count: 0 };
             this.shared.overflow.set(k, counted);
-            this.shared.findings.push(this.factory.make(category, detail, 'additional occurrences', counted));
+            const finding = this.factory.make(category, detail, 'additional occurrences', counted);
+            finding.action = act;
+            if (action === 'info')
+                this.run.superseded.add(finding);
+            this.shared.findings.push(finding);
         }
         counted.count = Number(counted.count) + 1;
+        return { action: act };
+    }
+    /** Reports content that goes whatever the overrides say: its action is strip, or reject when the caller asked for that. */
+    removal(category, detail, location, data) {
+        const act = this.factory.actionFor(category, detail);
+        return this.report(category, detail, location, data, act === 'info' ? 'strip' : act);
+    }
+    /** Adds findings from another package as they are, such as those a plugin made inside a file. */
+    push(findings) {
+        this.shared.findings.push(...findings);
+        this.shared.strips += findings.filter(f => f.action === 'strip').length;
     }
     /** Reports a link, classified by pdf-defuse's checks of its target. */
     link(target, location, data = {}) {
         const v = (0, links_1.checkLink)(target);
-        this.report(v.category, v.detail, location, { ...data, target: (0, exports.clip)(target, 2000), ...(v.host ? { host: (0, exports.clip)(v.host) } : {}) });
+        return this.report(v.category, v.detail, location, { ...data, target: (0, exports.clip)(target, 2000), ...(v.host ? { host: (0, exports.clip)(v.host) } : {}) });
+    }
+    /**
+     * Reports a safe link whose text or tooltip names another site than the one it opens, as LINK/TEXT_MISMATCH. Returns
+     * undefined when no label names a site, or every site a label names is the target's.
+     */
+    labelMismatch(target, labels, location, data = {}) {
+        const label = (0, links_1.mismatchedLabel)(target, labels);
+        if (label === undefined)
+            return undefined;
+        return this.report(types_1.OfficeCategory.Link, types_1.OfficeDetail.TextMismatch, location, { ...data, target: (0, exports.clip)(target, 2000), label: (0, exports.clip)(label) });
     }
     /**
      * Reports a reference that loads from outside the file on its own. It is EXTERNAL/LOCAL_FILE, with `kind` saying
@@ -67,45 +114,75 @@ class RunContext {
     external(detail, target, location, data, kind) {
         const d = { ...data, target: (0, exports.clip)(target, 2000) };
         if ((0, links_1.isLocalTarget)(target))
-            this.report(types_1.OfficeCategory.External, types_1.OfficeDetail.LocalFile, location, { ...d, kind });
-        else
-            this.report(types_1.OfficeCategory.External, detail, location, d);
+            return this.report(types_1.OfficeCategory.External, types_1.OfficeDetail.LocalFile, location, { ...d, kind });
+        return this.report(types_1.OfficeCategory.External, detail, location, d);
     }
     /**
      * Tokenizes XML text, or Office's VML dialect, handing the events to `handler`. A document type declaration is
      * XML/DOCTYPE without an internal subset and XML/INTERNAL_SUBSET with one. A reference to an external entity in
      * content is XML/EXTERNAL_ENTITY.
      */
-    async parseXml(part, chunks, handler, vml = false) {
+    async parseXml(part, chunks, handler, vml = false, plan, after) {
         const notes = {
             doctype: d => {
                 const ids = { ...(d.publicId === undefined ? {} : { publicId: (0, exports.clip)(d.publicId) }), ...(d.systemId === undefined ? {} : { systemId: (0, exports.clip)(d.systemId) }) };
-                if (!d.internalSubset)
-                    this.report(types_1.OfficeCategory.Xml, types_1.OfficeDetail.Doctype, part, { part, name: (0, exports.clip)(d.name), ...ids });
+                if (!d.internalSubset) {
+                    if (this.report(types_1.OfficeCategory.Xml, types_1.OfficeDetail.Doctype, part, { part, name: (0, exports.clip)(d.name), ...ids }).action === 'strip' && plan)
+                        plan.part(part).doctype = true;
+                }
                 else {
                     const counts = { entities: d.entities, externalEntities: d.externalEntities, attributeDefaults: d.attributeDefaults, skipped: d.skipped };
-                    this.report(types_1.OfficeCategory.Xml, types_1.OfficeDetail.InternalSubset, part, { part, name: (0, exports.clip)(d.name), ...ids, ...counts });
+                    if (this.report(types_1.OfficeCategory.Xml, types_1.OfficeDetail.InternalSubset, part, { part, name: (0, exports.clip)(d.name), ...ids, ...counts }).action === 'strip' && plan)
+                        plan.part(part).subset = true;
                 }
             },
-            externalEntity: r => this.report(types_1.OfficeCategory.Xml, types_1.OfficeDetail.ExternalEntity, part, { part, entity: (0, exports.clip)(r.name), target: (0, exports.clip)(r.systemId, 2000), ...(r.publicId === undefined ? {} : { publicId: (0, exports.clip)(r.publicId) }) }),
+            externalEntity: r => {
+                const reported = this.report(types_1.OfficeCategory.Xml, types_1.OfficeDetail.ExternalEntity, part, {
+                    part,
+                    entity: (0, exports.clip)(r.name),
+                    target: (0, exports.clip)(r.systemId, 2000),
+                    ...(r.publicId === undefined ? {} : { publicId: (0, exports.clip)(r.publicId) }),
+                });
+                if (!plan)
+                    return;
+                const p = plan.part(part);
+                p.hasExternal = true;
+                if (reported.action === 'strip')
+                    p.external = true;
+            },
         };
         const t = new xml_1.XmlTokenizer(handler, this.xmlLimits, part, { vml, notes, budget: this.shared.budget });
-        for await (const chunk of chunks)
+        // `after` runs between chunks, so a handler can hand what it gathered to something that waits.
+        for await (const chunk of chunks) {
             t.write(chunk);
+            await after?.();
+        }
         t.end();
+        await after?.();
     }
 }
 exports.RunContext = RunContext;
+/** The context of rules that fill in a rewrite plan: a ZIP package's, or a flat XML file's. */
+class PlanContext extends RunContext {
+    plan;
+    constructor(
+    /** What the rewrite removes, which the rules fill in as they report. */
+    plan, factory, xmlLimits, settings, shared) {
+        super(factory, xmlLimits, settings, shared);
+        this.plan = plan;
+    }
+}
+exports.PlanContext = PlanContext;
 /** The context of the rules that read a ZIP archive. */
-class ZipContext extends RunContext {
+class ZipContext extends PlanContext {
     zip;
-    constructor(zip, factory, xmlLimits, settings, shared) {
-        super(factory, xmlLimits, settings, shared);
+    constructor(zip, plan, factory, xmlLimits, settings, shared) {
+        super(plan, factory, xmlLimits, settings, shared);
         this.zip = zip;
     }
     /** Inflates an entry and tokenizes it as XML, or as Office's VML dialect, handing the events to `handler`. */
     parse(entry, handler, vml = false) {
-        return this.parseXml(entry.name, this.zip.read(entry), handler, vml);
+        return this.parseXml(entry.name, this.zip.read(entry), handler, vml, this.plan);
     }
     /** Inflates an entry, which checks it, hands each chunk to `visit`, and tells whether its bytes are an OLE file. */
     async drain(entry, visit) {

package/dist/engine.d.ts

@@ -1,5 +1,16 @@
-import { type ByteSource, type OfficeInspection, type OfficeOptions } from './types';
+import { type ByteSink, type ByteSource, type OfficeDisarmResult, type OfficeInspection, type OfficeOptions } from './types';
 /** 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. */
 export declare function inspectOffice(bytes: Uint8Array, options?: OfficeOptions): Promise<OfficeInspection>;
+/**
+ * Writes a defused copy of `source` to `sink`. Nothing reaches the sink unless the output passes inspection. The
+ * source is closed when the run ends.
+ */
+export declare function disarmOfficeSource(source: ByteSource, sink: ByteSink, options?: OfficeOptions): Promise<OfficeDisarmResult>;
+/** Internal entry that carries the depth of a file inside another, and the deadline it shares with the upload. */
+export declare function disarmAtDepth(source: ByteSource, sink: ByteSink, options: OfficeOptions, depth: number, deadline?: number | undefined): Promise<OfficeDisarmResult>;
+/** Defuses Office or OpenDocument bytes. `bytes` holds the output unless the file was rejected. */
+export declare function disarmOffice(bytes: Uint8Array, options?: OfficeOptions): Promise<OfficeDisarmResult & {
+    bytes?: Uint8Array;
+}>;