@patrickdk77/office-defuse 0.1.1 → 0.2.1

package/dist/package.d.ts

@@ -1,3 +1,17 @@
 import type { ZipContext } from './context';
+import type { Format } from './formats';
+import type { ZipArchive, ZipEntry } from './zip';
+/**
+ * The package a ZIP archive's markers name: OOXML by [Content_Types].xml, OpenDocument by a mimetype entry or a
+ * manifest. Throws for an archive with both or neither.
+ */
+export declare function packageKind(zip: ZipArchive): {
+    kind: 'ooxml';
+    contentTypes: ZipEntry;
+} | {
+    kind: 'odf';
+};
 /** Inspects an OOXML or OpenDocument package, which its markers name. */
 export declare function inspectPackage(ctx: ZipContext): Promise<void>;
+/** Names an OOXML or OpenDocument package's format as its inspection does, without the rules. */
+export declare function namePackage(ctx: ZipContext): Promise<Format>;

package/dist/package.js

@@ -1,21 +1,37 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.packageKind = packageKind;
 exports.inspectPackage = inspectPackage;
+exports.namePackage = namePackage;
 const errors_1 = require("./errors");
 const odf_1 = require("./odf");
 const ooxml_1 = require("./ooxml");
 const types_1 = require("./types");
-/** Inspects an OOXML or OpenDocument package, which its markers name. */
-async function inspectPackage(ctx) {
-    const zip = ctx.zip;
+/**
+ * The package a ZIP archive's markers name: OOXML by [Content_Types].xml, OpenDocument by a mimetype entry or a
+ * manifest. Throws for an archive with both or neither.
+ */
+function packageKind(zip) {
     const contentTypes = zip.get('[Content_Types].xml');
     const odf = zip.entries.some(e => e.name === 'mimetype') || zip.get('META-INF/manifest.xml') !== undefined;
     if (contentTypes && odf)
         throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.AmbiguousFormat, 'The file has both [Content_Types].xml and an OpenDocument mimetype or manifest', { reason: 'OOXML and OpenDocument markers' });
     if (contentTypes)
-        await (0, ooxml_1.inspectOoxml)(ctx, contentTypes);
-    else if (odf)
-        await (0, odf_1.inspectOdf)(ctx);
+        return { kind: 'ooxml', contentTypes };
+    if (odf)
+        return { kind: 'odf' };
+    throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, 'The archive has neither [Content_Types].xml nor an OpenDocument mimetype or manifest', { reason: 'a plain ZIP archive' });
+}
+/** Inspects an OOXML or OpenDocument package, which its markers name. */
+async function inspectPackage(ctx) {
+    const k = packageKind(ctx.zip);
+    if (k.kind === 'ooxml')
+        await (0, ooxml_1.inspectOoxml)(ctx, k.contentTypes);
     else
-        throw new errors_1.StopError(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unrecognized, 'The archive has neither [Content_Types].xml nor an OpenDocument mimetype or manifest', { reason: 'a plain ZIP archive' });
+        await (0, odf_1.inspectOdf)(ctx);
+}
+/** Names an OOXML or OpenDocument package's format as its inspection does, without the rules. */
+async function namePackage(ctx) {
+    const k = packageKind(ctx.zip);
+    return k.kind === 'ooxml' ? (0, ooxml_1.nameOoxml)(ctx, k.contentTypes) : (await (0, odf_1.nameOdf)(ctx)).format;
 }

package/dist/plan.d.ts

@@ -0,0 +1,104 @@
+import type { CfbEntry, CompoundFile } from './cfb';
+import type { SpillSink } from './io';
+import type { OoxmlGraph } from './ooxml';
+import type { OfficeFinding } from './types';
+import type { ZipEntry } from './zip';
+/** What the rewrite does to one element of an XML part. */
+export interface ElementEdit {
+    /** The element goes, with everything inside it. */
+    remove?: boolean;
+    /** Its tags go and its content stays, as with a hyperlink around text. */
+    unwrap?: boolean;
+    /** Attributes left out, each as its namespace URI, a space and its local name. */
+    strip?: Set<string>;
+    /** Attribute values replaced, by qualified name. */
+    set?: Map<string, string>;
+    /** The element's content replaced with this text, as with base64 data a plugin rewrote. */
+    content?: string;
+}
+/** The key `ElementEdit.strip` takes for an attribute. */
+export declare const attributeKey: (ns: string, local: string) => string;
+/** A Word field the rewrite removes, by the element numbers of its marks. Its result stays. */
+export interface FieldMarks {
+    begin: number;
+    separate?: number;
+    end?: number;
+    /** A w:fldSimple, whose tags go and whose result runs stay. */
+    simple: boolean;
+}
+/** What the rewrite does inside one XML part. */
+export interface PartPlan {
+    elements: Map<number, ElementEdit>;
+    fields: FieldMarks[];
+    /** The part has an internal subset that goes. Its entity references are expanded and its defaults written out. */
+    subset: boolean;
+    /** References to external entities in the part go. */
+    external: boolean;
+    /** A document type declaration without an internal subset goes. */
+    doctype: boolean;
+    /** The part refers to an external entity. */
+    hasExternal: boolean;
+}
+/** An OpenDocument object element whose fate waits for the plugins' verdict on the entry it names. */
+export interface DeferredObject {
+    part: string;
+    index: number;
+    /** The key of the entry it refers to. */
+    target: string;
+    finding?: OfficeFinding;
+    strips: boolean;
+}
+/** Everything a strip finding names in a ZIP package, for the rewrite. */
+export declare class PackagePlan {
+    readonly parts: Map<string, PartPlan>;
+    /** Entries that go with every reference to them, by nameKey. */
+    readonly drop: Set<string>;
+    /** OpenDocument folders that go whole, as nameKey prefixes ending in "/". */
+    readonly folders: Set<string>;
+    /** Relationship Ids that go, by the name of their relationships part. */
+    readonly rels: Map<string, Set<string>>;
+    /** Excel 4.0 macro sheets that become empty worksheets, by nameKey. */
+    readonly sheets: Set<string>;
+    /** Entries whose bytes a plugin replaced, by nameKey. */
+    readonly replace: Map<string, SpillSink>;
+    /** OpenDocument object references, decided once the plugins have seen the entries they name. */
+    readonly objects: DeferredObject[];
+    /** What the OOXML rules read of the package's parts and relationships. */
+    graph?: OoxmlGraph;
+    /** What the OpenDocument rules read of the package's layout. */
+    odf?: OdfLayout;
+    part(name: string): PartPlan;
+    /** Adds an edit to an element. Removing it covers every other edit. */
+    element(part: string, index: number, edit: ElementEdit): void;
+    dropRelationship(relsPart: string, id: string): void;
+}
+/** The entries of a ZIP package the rewrite needs besides the plan: what the format rules found. */
+export interface OdfLayout {
+    mimetype?: ZipEntry;
+    manifest?: ZipEntry;
+    /** The media type the package declares, which the output's mimetype entry holds. */
+    mediaType: string;
+}
+/** Everything a strip finding names in a compound file, for the rewrite. */
+export declare class CompoundPlan {
+    /** Streams and storages that go, each with everything under it. */
+    readonly drop: Set<CfbEntry>;
+    /** Streams whose content a plugin replaced. */
+    readonly replace: Map<CfbEntry, SpillSink>;
+    /** Storages whose content a plugin replaced with a compound file of its own, read from what it wrote. */
+    readonly grafts: Map<CfbEntry, CompoundFile>;
+}
+/** A range of an RTF file the rewrite leaves out, or replaces with `text` and then the bytes of the file at `copy`. */
+export interface RtfCut {
+    start: number;
+    end: number;
+    text?: Uint8Array;
+    copy?: [number, number];
+}
+/** What the output of a Flat OPC package keeps of the file besides its parts. */
+export interface FlatOpcLayout {
+    /** The prolog's mso-application processing instructions, which name the application that opens the file. */
+    instructions: string[];
+    /** Each part's attributes besides its name and content type, such as pkg:compression, by key. */
+    extra: Map<string, Array<[string, string]>>;
+}

package/dist/plan.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CompoundPlan = exports.PackagePlan = exports.attributeKey = void 0;
+/** The key `ElementEdit.strip` takes for an attribute. */
+const attributeKey = (ns, local) => `${ns} ${local}`;
+exports.attributeKey = attributeKey;
+/** Everything a strip finding names in a ZIP package, for the rewrite. */
+class PackagePlan {
+    parts = new Map();
+    /** Entries that go with every reference to them, by nameKey. */
+    drop = new Set();
+    /** OpenDocument folders that go whole, as nameKey prefixes ending in "/". */
+    folders = new Set();
+    /** Relationship Ids that go, by the name of their relationships part. */
+    rels = new Map();
+    /** Excel 4.0 macro sheets that become empty worksheets, by nameKey. */
+    sheets = new Set();
+    /** Entries whose bytes a plugin replaced, by nameKey. */
+    replace = new Map();
+    /** OpenDocument object references, decided once the plugins have seen the entries they name. */
+    objects = [];
+    /** What the OOXML rules read of the package's parts and relationships. */
+    graph;
+    /** What the OpenDocument rules read of the package's layout. */
+    odf;
+    part(name) {
+        let p = this.parts.get(name);
+        if (!p) {
+            p = { elements: new Map(), fields: [], subset: false, external: false, doctype: false, hasExternal: false };
+            this.parts.set(name, p);
+        }
+        return p;
+    }
+    /** Adds an edit to an element. Removing it covers every other edit. */
+    element(part, index, edit) {
+        const elements = this.part(part).elements;
+        const had = elements.get(index);
+        if (!had) {
+            elements.set(index, edit);
+            return;
+        }
+        if (had.remove || edit.remove) {
+            elements.set(index, { remove: true });
+            return;
+        }
+        had.unwrap ||= edit.unwrap;
+        if (edit.strip)
+            had.strip = new Set([...(had.strip ?? []), ...edit.strip]);
+        if (edit.set)
+            had.set = new Map([...(had.set ?? []), ...edit.set]);
+        if (edit.content !== undefined)
+            had.content = edit.content;
+    }
+    dropRelationship(relsPart, id) {
+        let ids = this.rels.get(relsPart);
+        if (!ids) {
+            ids = new Set();
+            this.rels.set(relsPart, ids);
+        }
+        ids.add(id);
+    }
+}
+exports.PackagePlan = PackagePlan;
+/** Everything a strip finding names in a compound file, for the rewrite. */
+class CompoundPlan {
+    /** Streams and storages that go, each with everything under it. */
+    drop = new Set();
+    /** Streams whose content a plugin replaced. */
+    replace = new Map();
+    /** Storages whose content a plugin replaced with a compound file of its own, read from what it wrote. */
+    grafts = new Map();
+}
+exports.CompoundPlan = CompoundPlan;

package/dist/plugins.d.ts

@@ -0,0 +1,8 @@
+import type { ContainedFilePlugin, OfficeOptions } from './types';
+/**
+ * Defuses Office and OpenDocument files inside other files, with `options` when given. Without them, it takes the
+ * options of the office-defuse run that found the file, or none when another package found it. `limits.nestingDepth`
+ * applies to the depth in the context. The file's findings go into the containing file's report, and its output's
+ * findings into the output's report, each with its `weight`.
+ */
+export declare function officePlugin(options?: OfficeOptions): ContainedFilePlugin;

package/dist/plugins.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.officePlugin = officePlugin;
+const contained_1 = require("./contained");
+const detect_1 = require("./detect");
+const engine_1 = require("./engine");
+const score_1 = require("./score");
+/**
+ * Defuses Office and OpenDocument files inside other files, with `options` when given. Without them, it takes the
+ * options of the office-defuse run that found the file, or none when another package found it. `limits.nestingDepth`
+ * applies to the depth in the context. The file's findings go into the containing file's report, and its output's
+ * findings into the output's report, each with its `weight`.
+ */
+function officePlugin(options) {
+    return {
+        kind: 'file',
+        name: 'office',
+        // It takes what detectOffice names: the content decides, whatever the name says.
+        accepts: async (f) => (await (0, detect_1.detectOfficeSource)(f.source, { name: f.name, declaredType: f.declaredType })) !== undefined,
+        async process(file, sink, context) {
+            const run = options ?? context[contained_1.RUN_OPTIONS] ?? {};
+            const r = await (0, engine_1.disarmAtDepth)(file.source, sink, run, context.depth, context.deadline);
+            // A container in another package scores these by the weights this run used.
+            for (const f of [...r.before.findings, ...(r.after?.findings ?? [])])
+                f.weight = (0, score_1.weightOf)(f, run);
+            const findings = r.before.findings;
+            // The sink holds the rewritten file, also when nothing was removed.
+            if (r.status === 'clean')
+                return { result: 'passed', findings, outputFindings: r.after?.findings };
+            if (r.status === 'defused')
+                return { result: 'scrubbed', findings, outputFindings: r.after?.findings };
+            return { result: 'removed', findings };
+        },
+    };
+}

package/dist/ppt.js

@@ -36,11 +36,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.powerPointRules = powerPointRules;
 const zlib = __importStar(require("node:zlib"));
 const cfb_1 = require("./cfb");
+const contained_1 = require("./contained");
 const context_1 = require("./context");
 const errors_1 = require("./errors");
 const io_1 = require("./io");
 const links_1 = require("./links");
 const objects_1 = require("./objects");
+const offcrypto_1 = require("./offcrypto");
 const oleobj_1 = require("./oleobj");
 const types_1 = require("./types");
 /** Record types of the PowerPoint binary format (MS-PPT 2.13.24). */
@@ -56,6 +58,7 @@ const T = {
     cString: 0x0fba,
     exHyperlink: 0x0fd7,
     exHyperlinkAtom: 0x0fd3,
+    cryptSession: 0x2f14,
 };
 /** ExVideoContainer, ExMIDIAudioContainer and ExWAVAudioLinkContainer, whose path names a file outside the presentation. */
 const MEDIA_LINKS = new Set([0x1005, 0x100d, 0x1010]);
@@ -71,16 +74,18 @@ const header = (b) => ({ version: b[0] & 0x0f, instance: (b[0] | (b[1] << 8)) >>
  */
 async function powerPointRules(ctx, cfb, stream) {
     const location = stream.name;
-    const source = cfb.source(stream);
-    const reader = new io_1.Reader(source, stream.size, 16384, 8);
+    let source = cfb.source(stream);
+    let reader = new io_1.Reader(source, stream.size, 16384, 8);
     const persist = new Map();
     const current = cfb.child(cfb.root, 'Current User');
     if (current?.kind === 'stream') {
         const cu = await cfb.source(current).read(0, 24);
         if (cu.length >= 20 && header(cu).type === T.currentUserAtom) {
-            if (u32(cu, 12) === ENCRYPTED_TOKEN)
-                throw new errors_1.StopError(types_1.OfficeCategory.Encrypted, types_1.OfficeDetail.PasswordRequired, 'The presentation is encrypted', { stream: location });
             await readPersist(reader, stream.size, u32(cu, 16), persist, ctx.settings.deadline);
+            if (u32(cu, 12) === ENCRYPTED_TOKEN) {
+                source = await decryptPresentation(ctx, reader, stream, u32(cu, 16), persist);
+                reader = new io_1.Reader(source, stream.size, 16384, 8);
+            }
         }
     }
     const storages = new Map();
@@ -128,6 +133,37 @@ async function powerPointRules(ctx, cfb, stream) {
         await storageRules(ctx, source, s, role, `${location}, offset ${s.offset}`);
     }
 }
+/**
+ * The PowerPoint Document stream of an encrypted presentation, decrypted (MS-PPT 2.3.7). The current edit names the
+ * persist object that holds the CryptSession10Container, whose data is an RC4 CryptoAPI EncryptionHeader. Each other
+ * persist object, its record header included, is RC4 with the key of block number its persist id. The edits and
+ * persist directories were never encrypted.
+ */
+async function decryptPresentation(ctx, reader, stream, edit, persist) {
+    const required = (reason) => new errors_1.StopError(types_1.OfficeCategory.Encrypted, types_1.OfficeDetail.PasswordRequired, `The presentation is encrypted: ${reason}`, { stream: stream.name, reason });
+    const u = await reader.read(edit, 40);
+    const sessionAt = u.length >= 40 && header(u).type === T.userEditAtom ? persist.get(u32(u, 36)) : undefined;
+    if (sessionAt === undefined || sessionAt + 8 > stream.size)
+        throw required('the current edit names no CryptSession10Container');
+    const h = header(await reader.read(sessionAt, 8));
+    if (h.type !== T.cryptSession)
+        throw required('the current edit names no CryptSession10Container');
+    const keyOf = (0, offcrypto_1.unlockPresentation)(ctx, await reader.read(sessionAt + 8, Math.min(h.length, 65536)), stream.name);
+    if (stream.size > ctx.settings.decompressedBytes)
+        throw new errors_1.StopError(types_1.OfficeCategory.Limit, types_1.OfficeDetail.DecompressedSize, `The encrypted stream ${stream.name} is ${stream.size} bytes`, { name: stream.name, size: stream.size, limit: ctx.settings.decompressedBytes });
+    const copy = Buffer.from(await reader.read(0, stream.size));
+    for (const [id, offset] of persist) {
+        (0, errors_1.checkTime)(ctx.settings.deadline);
+        if (offset === sessionAt || offset + 8 > copy.length)
+            continue;
+        const rc4 = keyOf(id);
+        const head = rc4.crypt(copy.subarray(offset, offset + 8));
+        const length = Math.min(copy.length - offset - 8, u32(head, 4));
+        copy.set(head, offset);
+        copy.set(rc4.crypt(copy.subarray(offset + 8, offset + 8 + length)), offset + 8);
+    }
+    return (0, io_1.bufferSource)(copy);
+}
 /** Reads the persist directories of the current edit and every edit before it. Newer entries win. */
 async function readPersist(reader, size, start, persist, deadline) {
     const seen = new Set();
@@ -193,7 +229,11 @@ async function storageRules(ctx, source, s, role, location) {
     (0, objects_1.nestedNotes)(ctx, cfb, location);
     if (role === 'control')
         ctx.report(types_1.OfficeCategory.Control, types_1.OfficeDetail.ActiveX, location, { storage: location, ...(cfb.root.clsid === '00000000-0000-0000-0000-000000000000' ? {} : { clsid: cfb.root.clsid }) });
-    await (0, objects_1.compoundRules)(ctx, cfb, location, role === 'object');
+    // An object's storage goes to the plugins as the compound file it is. The rewrite cannot change the presentation's
+    // records, so only a plugin that passes the object keeps it in the output.
+    const size = await inner.size();
+    const decision = role === 'object' ? await (0, contained_1.decideContained)(ctx, { location, chunks: () => (0, io_1.chunksOf)(inner, size) }) : undefined;
+    await (0, objects_1.compoundRules)(ctx, cfb, location, role === 'object', undefined, decision);
 }
 function unreadable(ctx, role, location, reason) {
     if (role === 'vba')

package/dist/rewrite-cfb.d.ts

@@ -0,0 +1,14 @@
+import type { CfbEntry, CompoundFile } from './cfb';
+import { type CfbTree } from './cfb-writer';
+import type { RunState } from './context';
+import { CompoundPlan } from './plan';
+import type { ByteSink } from './types';
+/**
+ * Writes a compound file without the streams and storages the plan drops. A stream a plugin replaced takes the bytes
+ * the plugin wrote, and an object's storage a plugin replaced takes the storages and streams of the compound file the
+ * plugin wrote. Every other stream is copied as it is. Sectors no stream holds, the rest of each stream's last sector
+ * and anything after the last sector are not written.
+ */
+export declare function writeCompound(run: RunState, cfb: CompoundFile, plan: CompoundPlan, sink: ByteSink): Promise<void>;
+/** A storage and everything under it, as the root of a compound file of its own. */
+export declare function subtree(cfb: CompoundFile, storage: CfbEntry): CfbTree;

package/dist/rewrite-cfb.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeCompound = writeCompound;
+exports.subtree = subtree;
+const cfb_writer_1 = require("./cfb-writer");
+const plan_1 = require("./plan");
+/** The nodes of a storage's subtree, without what the plan drops, with what plugins returned in place of the rest. */
+function nodes(cfb, storage, plan, opened) {
+    const out = [];
+    for (const c of storage.children) {
+        if (plan.drop.has(c))
+            continue;
+        const replaced = plan.replace.get(c);
+        if (c.kind === 'stream') {
+            if (!replaced) {
+                out.push({ kind: 'stream', name: c.name, size: c.size, source: cfb.source(c) });
+                continue;
+            }
+            const source = replaced.source();
+            opened.push(source);
+            out.push({ kind: 'stream', name: c.name, size: replaced.length, source });
+            continue;
+        }
+        const graft = plan.grafts.get(c);
+        if (graft)
+            out.push({ kind: 'storage', name: c.name, clsid: graft.root.clsid === '00000000-0000-0000-0000-000000000000' ? '' : graft.root.clsid, children: nodes(graft, graft.root, plan, opened) });
+        else
+            out.push({ kind: 'storage', name: c.name, clsid: c.clsid === '00000000-0000-0000-0000-000000000000' ? '' : c.clsid, children: nodes(cfb, c, plan, opened) });
+    }
+    return out;
+}
+/**
+ * Writes a compound file without the streams and storages the plan drops. A stream a plugin replaced takes the bytes
+ * the plugin wrote, and an object's storage a plugin replaced takes the storages and streams of the compound file the
+ * plugin wrote. Every other stream is copied as it is. Sectors no stream holds, the rest of each stream's last sector
+ * and anything after the last sector are not written.
+ */
+async function writeCompound(run, cfb, plan, sink) {
+    const clsid = cfb.root.clsid === '00000000-0000-0000-0000-000000000000' ? '' : cfb.root.clsid;
+    const opened = [];
+    try {
+        await (0, cfb_writer_1.writeCfb)({ clsid, children: nodes(cfb, cfb.root, plan, opened) }, sink, run.deadline);
+    }
+    finally {
+        for (const s of opened)
+            await s.close?.();
+    }
+}
+/** A storage and everything under it, as the root of a compound file of its own. */
+function subtree(cfb, storage) {
+    return { clsid: storage.clsid === '00000000-0000-0000-0000-000000000000' ? '' : storage.clsid, children: nodes(cfb, storage, new plan_1.CompoundPlan(), []) };
+}

package/dist/rewrite-rtf.d.ts

@@ -0,0 +1,9 @@
+import type { RunState } from './context';
+import type { RtfCut } from './plan';
+import type { ByteSink, ByteSource } from './types';
+/**
+ * Writes an RTF file without the ranges the cuts name: the groups of the destinations a strip finding names, and any
+ * bytes after the group that closes the document. A cut can put text in place of what it removes, such as an object's
+ * result group in place of the object. Everything else keeps its bytes.
+ */
+export declare function writeRtf(run: RunState, source: ByteSource, size: number, cuts: RtfCut[], sink: ByteSink): Promise<void>;

package/dist/rewrite-rtf.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeRtf = writeRtf;
+const errors_1 = require("./errors");
+/** Sorts cuts and drops each one that lies inside another, so they apply in one pass. */
+function normalize(cuts) {
+    const sorted = [...cuts].sort((a, b) => a.start - b.start || b.end - a.end);
+    const out = [];
+    let reach = 0;
+    for (const c of sorted) {
+        if (c.start < reach)
+            continue;
+        out.push(c);
+        reach = Math.max(reach, c.end);
+    }
+    return out;
+}
+/** Copies the bytes from `from` to `to` of the source. */
+async function copyRange(run, source, from, to, sink) {
+    for (let at = from; at < to; at += 262144) {
+        (0, errors_1.checkTime)(run.deadline);
+        const want = Math.min(262144, to - at);
+        const b = await source.read(at, want);
+        if (b.length !== want)
+            throw Object.assign(new Error(`The source returned ${b.length} bytes at offset ${at} where ${want} were expected`), { code: 'EIO' });
+        await sink.write(b);
+    }
+}
+/**
+ * Writes an RTF file without the ranges the cuts name: the groups of the destinations a strip finding names, and any
+ * bytes after the group that closes the document. A cut can put text in place of what it removes, such as an object's
+ * result group in place of the object. Everything else keeps its bytes.
+ */
+async function writeRtf(run, source, size, cuts, sink) {
+    let pos = 0;
+    for (const c of normalize(cuts)) {
+        await copyRange(run, source, pos, Math.min(c.start, size), sink);
+        if (c.text)
+            await sink.write(c.text);
+        if (c.copy)
+            await copyRange(run, source, c.copy[0], Math.min(c.copy[1], size), sink);
+        pos = Math.max(pos, c.end);
+    }
+    await copyRange(run, source, pos, size, sink);
+}

package/dist/rewrite-xml.d.ts

@@ -0,0 +1,36 @@
+import type { ElementEdit, PartPlan } from './plan';
+import { type XmlElement, type XmlLimits } from './xml';
+/** A range of a part's decoded text that the rewrite leaves out, or replaces with `text`. */
+export interface Edit {
+    start: number;
+    end: number;
+    text?: string;
+}
+/** What the rewrite of one part does besides the plan: edits that follow from what was dropped elsewhere. */
+export interface RewriteRules {
+    /** The edit an element gets, from the plan or from a reference to something that goes. */
+    element(el: XmlElement): ElementEdit | undefined;
+    /** Whether an element goes once every element in it went, as a list that would otherwise be left empty. */
+    collapses?(el: XmlElement): boolean;
+    /** Text to add before the root element's end tag, asked for when it is reached. */
+    append?(): string;
+    /** Whether an element belongs to WordprocessingML, whose fields the plan names. */
+    word?(el: XmlElement): boolean;
+}
+export interface PartRewrite {
+    edits: Edit[];
+    /** The plan removes the root element, so the part goes instead. */
+    rootRemoved: boolean;
+}
+/** A start tag written out from what the tokenizer read, with the edit's attributes left out or changed. */
+export declare function startTag(el: XmlElement, edit?: ElementEdit): string;
+/**
+ * Reads a part again with the tokenizer and returns the edits its rewrite makes. The part was read once already, by
+ * the same tokenizer with the same limits, so this reading sees the same elements in the same order.
+ */
+export declare function partEdits(chunks: AsyncIterable<Uint8Array>, part: string, limits: XmlLimits, vml: boolean, plan: PartPlan | undefined, rules: RewriteRules): Promise<PartRewrite>;
+/**
+ * Applies edits to a part as its bytes arrive, and yields the result in the part's encoding, its byte order mark
+ * included. Text the edits do not touch keeps its characters, so it keeps its bytes.
+ */
+export declare function splice(chunks: AsyncIterable<Uint8Array>, edits: Edit[]): AsyncGenerator<Uint8Array>;