@patrickdk77/office-defuse 0.1.1 → 0.2.1

package/dist/engine.d.ts

@@ -1,5 +1,70 @@
-import { type ByteSource, 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. */
 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;
+}>;
+export {};

package/dist/engine.js

@@ -1,14 +1,26 @@
 "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;
+exports.disarmAtDepth = disarmAtDepth;
+exports.disarmOffice = disarmOffice;
 const cfb_1 = require("./cfb");
 const context_1 = require("./context");
 const errors_1 = require("./errors");
 const findings_1 = require("./findings");
+const flat_1 = require("./flat");
 const io_1 = require("./io");
 const ole_1 = require("./ole");
 const package_1 = require("./package");
+const rewrite_cfb_1 = require("./rewrite-cfb");
+const rewrite_rtf_1 = require("./rewrite-rtf");
+const rewrite_zip_1 = require("./rewrite-zip");
 const rtf_1 = require("./rtf");
 const score_1 = require("./score");
 const types_1 = require("./types");
@@ -37,19 +49,31 @@ function resolveLimits(given = {}) {
         rtfDepth: given.rtfDepth ?? DEFAULT_LIMITS.rtfDepth,
         fileSize: given.fileSize,
         timeMs: given.timeMs,
+        nestingDepth: given.nestingDepth,
     };
 }
+const xmlLimitsOf = (limits) => ({
+    depth: limits.xmlDepth,
+    tokenSize: limits.xmlTokenSize,
+    entityDepth: limits.xmlEntityDepth,
+    entityExpansions: limits.xmlEntityExpansions,
+    entitySize: limits.xmlEntitySize,
+});
+const PLUGIN_KEPT = new Set([types_1.OfficeDetail.PluginPassed, types_1.OfficeDetail.PluginScrubbed]);
 /**
  * `incomplete` marks a run that stopped before it read the whole package. It is rejected without a score, whatever
- * the actions say, because an override can make the finding that stopped it look harmless.
+ * the actions say, because an override can make the finding that stopped it look harmless. In the check of an output,
+ * `isOutput`, the files plugins kept count in the score; in an upload they do not, and a file a plugin cleaned makes
+ * the upload strippable, since the output must be written.
  */
-function finish(findings, options, incomplete, format) {
+function finish(findings, options, incomplete, format, isOutput = false, superseded) {
     const named = { format: format?.format ?? '', mimeType: format?.mimeType ?? '' };
     if (incomplete)
         return { status: 'rejected', score: null, risk: types_1.OfficeRisk.Unknown, findings, ...named };
     const rejected = findings.some(f => f.action === 'reject');
-    const strippable = findings.some(f => f.action === 'strip');
-    const { score, risk } = (0, score_1.scoreFindings)(findings, options);
+    const strippable = findings.some(f => f.action === 'strip' || (!isOutput && f.detail === types_1.OfficeDetail.PluginScrubbed));
+    const scored = findings.filter(f => !superseded?.has(f) && (isOutput || !PLUGIN_KEPT.has(f.detail)));
+    const { score, risk } = (0, score_1.scoreFindings)(scored, options);
     return { status: rejected ? 'rejected' : strippable ? 'strippable' : 'clean', score, risk, findings, ...named };
 }
 /**
@@ -92,13 +116,15 @@ const ambiguous = (reason) => new errors_1.StopError(types_1.OfficeCategory.Pack
  * 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.
+ * 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.
  */
 async function openContainer(src, size, limits, settings) {
-    const head = await src.read(0, Math.min(8, size));
-    const cfbSignature = head.length === 8 && head.every((b, i) => b === cfb_1.CFB_SIGNATURE[i]);
+    const head = await src.read(0, Math.min(1024, size));
+    const cfbSignature = head.length >= 8 && cfb_1.CFB_SIGNATURE.every((b, i) => head[i] === b);
     const rtfSignature = Buffer.from(head.subarray(0, 4)).toString('latin1') === '{\\rt';
-    const probe = cfbSignature || rtfSignature
+    const xml = !cfbSignature && !rtfSignature && (0, flat_1.startsAsXml)(head);
+    const probe = cfbSignature || rtfSignature || xml
         ? await zip_1.ZipArchive.open(src, limits, settings.deadline).catch((e) => {
             if (e instanceof errors_1.StopError)
                 return undefined;
@@ -110,6 +136,11 @@ async function openContainer(src, size, limits, settings) {
             throw ambiguous('both RTF and a ZIP archive');
         return { kind: 'rtf' };
     }
+    if (xml) {
+        if (probe)
+            throw ambiguous('both XML and a ZIP archive');
+        return { kind: 'xml' };
+    }
     if (cfbSignature) {
         try {
             const cfb = await cfb_1.CompoundFile.open(src, settings, settings.deadline);
@@ -124,29 +155,68 @@ async function openContainer(src, size, limits, settings) {
     }
     return { kind: 'zip', zip: probe ?? (await zip_1.ZipArchive.open(src, limits, settings.deadline)) };
 }
-/** Inspects an Office or OpenDocument file without changing it. The source is closed when the run ends. */
-async function inspectOfficeSource(source, options = {}) {
+/** A run of the engine over one file at `depth`, with the deadline the whole upload shares. */
+function newRun(options, depth, deadline, verify) {
+    return {
+        options,
+        depth,
+        deadline,
+        temp: new io_1.TempDir(options.tempDir),
+        threshold: options.memoryThreshold ?? 8 * 1024 * 1024,
+        retained: 0,
+        verify,
+        kept: new Map(),
+        held: [],
+        superseded: new WeakSet(),
+        sources: [],
+    };
+}
+/** Releases what a run holds: the copies plugins returned and the temporary directory. */
+async function endRun(run) {
+    try {
+        for (const s of run.sources.splice(0))
+            await s.close?.();
+        for (const h of run.held.splice(0))
+            await h.dispose();
+    }
+    finally {
+        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 deadline = limits.timeMs !== undefined ? Date.now() + limits.timeMs : undefined;
-    const factory = new findings_1.FindingFactory(options.actionOverrides);
-    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,
-        password: options.password,
+        deadline: run.deadline,
+        passwords: typeof password === 'string' ? [password] : (password ?? []),
     };
-    const ctx = new context_1.RunContext(factory, {
-        depth: limits.xmlDepth,
-        tokenSize: limits.xmlTokenSize,
-        entityDepth: limits.xmlEntityDepth,
-        entityExpansions: limits.xmlEntityExpansions,
-        entitySize: limits.xmlEntitySize,
-    }, settings);
+    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);
+}
+/**
+ * Inspects `source` and leaves what the rewrite needs in `run.output`. It throws an I/O error instead of reporting a
+ * verdict on the file, and below depth 0 it throws a limit error from the family, which stops the whole upload.
+ */
+async function analyze(run, source) {
+    const options = run.options;
+    const deadline = run.deadline;
+    const { limits, settings, ctx } = runContext(run);
+    const factory = ctx.factory;
+    const findings = [];
+    const src = guarded(source);
+    const isOutput = run.verify !== undefined;
     try {
+        if (limits.nestingDepth !== undefined && run.depth > limits.nestingDepth)
+            throw new errors_1.NestingLimitError('Nesting limit exceeded');
         const size = await src.size();
         if (limits.fileSize !== undefined && size > limits.fileSize)
             throw new errors_1.StopError(types_1.OfficeCategory.Limit, types_1.OfficeDetail.FileSize, `${size} bytes`, { size, limit: limits.fileSize });
@@ -154,6 +224,11 @@ async function inspectOfficeSource(source, options = {}) {
         const container = await openContainer(src, size, limits, settings);
         if (container.kind === 'rtf')
             await (0, rtf_1.inspectRtf)(ctx, src, size);
+        else if (container.kind === 'xml') {
+            const output = await (0, flat_1.inspectFlat)(ctx, src, size, limits);
+            if (output && ctx.format)
+                run.output = output;
+        }
         else if (container.kind === 'cfb') {
             for (const n of container.cfb.notes)
                 findings.push(factory.make(types_1.OfficeCategory.Container, n.detail, undefined, { bytes: n.bytes }));
@@ -162,39 +237,219 @@ async function inspectOfficeSource(source, options = {}) {
         else {
             const zip = container.zip;
             for (const n of zip.notes)
-                findings.push(factory.make(types_1.OfficeCategory.Container, n.detail, undefined, { bytes: n.bytes }));
-            await (0, package_1.inspectPackage)(ctx.withZip(zip));
+                findings.push(factory.make(types_1.OfficeCategory.Container, n.detail, undefined, n.offset === undefined ? { bytes: n.bytes } : { bytes: n.bytes, offset: n.offset }));
+            const zctx = ctx.withZip(zip);
+            await (0, package_1.inspectPackage)(zctx);
+            if (ctx.format)
+                run.output = { kind: 'zip', zip, plan: zctx.plan, format: ctx.format };
         }
         findings.push(...ctx.findings);
-        return finish(findings, options, false, ctx.format);
+        if (run.temp.ioError !== undefined)
+            throw run.temp.ioError;
+        return finish(findings, options, false, ctx.format, isOutput, run.superseded);
     }
     catch (e) {
         if (src.failure !== undefined)
             throw src.failure;
+        if (run.temp.ioError !== undefined)
+            throw run.temp.ioError;
+        run.output = undefined;
         findings.push(...ctx.findings);
         if (e instanceof errors_1.StopError) {
             findings.push(factory.make(e.category, e.detail, e.location ?? (typeof e.data?.name === 'string' ? e.data.name : undefined), { ...e.data, reason: e.data?.reason ?? e.message }));
         }
-        else if (e?.code === 'DEFUSE_LIMIT') {
-            // The family's time limit, from this package or any other.
-            findings.push(factory.make(types_1.OfficeCategory.Limit, types_1.OfficeDetail.Time));
+        else if ((0, errors_1.stopsTree)(e) === 'DEFUSE_LIMIT') {
+            // The family's time and nesting limits, from this package or any other, stop the whole upload.
+            if (run.depth > 0)
+                throw e;
+            findings.push(limitFinding(factory, e));
+        }
+        else if ((0, errors_1.isIoError)(e)) {
+            throw e;
         }
         else {
             // Anything unexpected rejects the file rather than escaping as an exception.
             findings.push(factory.make(types_1.OfficeCategory.Package, types_1.OfficeDetail.Unreadable, undefined, { reason: String(e?.message ?? e).slice(0, 200) }));
         }
-        return finish(findings, options, true, ctx.format);
+        return finish(findings, options, true, ctx.format, isOutput);
+    }
+}
+async function closeSource(source) {
+    try {
+        await source.close?.();
+    }
+    catch {
+        // The verdict stands whether or not the source closes.
+    }
+}
+/** Inspects an Office or OpenDocument file without changing it. The source is closed when the run ends. */
+async function inspectOfficeSource(source, options = {}) {
+    const deadline = options.limits?.timeMs !== undefined ? Date.now() + options.limits.timeMs : undefined;
+    const run = newRun(options, 0, deadline);
+    try {
+        return await analyze(run, source);
     }
     finally {
+        await closeSource(source);
+        await endRun(run);
+    }
+}
+/** Inspects Office or OpenDocument bytes. */
+async function inspectOffice(bytes, options = {}) {
+    return inspectOfficeSource((0, io_1.bufferSource)(bytes), options);
+}
+/** Copies to the caller's sink. On failure it aborts the sink instead of closing it, so a partial copy does not look whole. */
+async function deliver(from, sink) {
+    try {
+        await (0, io_1.copyToSink)(from, sink);
+    }
+    catch (e) {
         try {
-            await source.close?.();
+            await sink.abort?.(e);
         }
         catch {
-            // The verdict stands whether or not the source closes.
+            /* the copy's error is the one to report */
         }
+        throw e;
     }
+    await sink.close();
 }
-/** Inspects Office or OpenDocument bytes. */
-async function inspectOffice(bytes, options = {}) {
-    return inspectOfficeSource((0, io_1.bufferSource)(bytes), options);
+/** Writes the rewrite of what the run read. */
+async function write(run, output, sink, source) {
+    const resolved = resolveLimits(run.options.limits);
+    const limits = xmlLimitsOf(resolved);
+    if (output.kind === 'zip')
+        await (0, rewrite_zip_1.writePackage)(run, output.zip, output.plan, output.format, limits, sink);
+    else if (output.kind === 'cfb')
+        await (0, rewrite_cfb_1.writeCompound)(run, output.cfb, output.plan, sink);
+    else if (output.kind === 'flatodf')
+        await (0, flat_1.writeFlatOdf)(run, source, output.plan, limits, sink);
+    else if (output.kind === 'flatopc')
+        await (0, flat_1.writeFlatOpc)(run, output, limits, resolved, sink);
+    else
+        await (0, rewrite_rtf_1.writeRtf)(run, source, output.size, output.cuts, sink);
+}
+/** Rejects the upload, keeping its findings and, unless a limit stopped the run, its score. */
+function refuse(before, finding, limited) {
+    before.findings.push(finding);
+    before.status = 'rejected';
+    if (limited) {
+        before.score = null;
+        before.risk = types_1.OfficeRisk.Unknown;
+    }
+    return { status: 'rejected', before, removed: [] };
+}
+/**
+ * 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.
+ */
+async function disarmOfficeSource(source, sink, options = {}) {
+    return disarmAtDepth(source, sink, options, 0);
+}
+/** Internal entry that carries the depth of a file inside another, and the deadline it shares with the upload. */
+async function disarmAtDepth(source, sink, options, depth, deadline = options.limits?.timeMs !== undefined ? Date.now() + options.limits.timeMs : undefined) {
+    const run = newRun(options, depth, deadline);
+    const factory = new findings_1.FindingFactory(options.actionOverrides);
+    let input = source;
+    try {
+        let before;
+        try {
+            // A caller's source can change between reads, so the inspection and the rewrite read one snapshot. A file
+            // inside another already has a source of the engine's, and one over the size limit is rejected unread.
+            const fileSize = options.limits?.fileSize;
+            if (depth === 0 && (fileSize === undefined || (await source.size()) <= fileSize)) {
+                const snapshot = new io_1.SpillSink(run.temp, run.threshold);
+                run.held.push(snapshot);
+                try {
+                    await (0, io_1.copyToSink)(source, snapshot, () => (0, errors_1.checkTime)(deadline));
+                }
+                finally {
+                    await snapshot.close();
+                }
+                input = snapshot.source();
+            }
+            before = await analyze(run, input);
+        }
+        catch (e) {
+            if ((0, errors_1.stopsTree)(e) !== 'DEFUSE_LIMIT' || depth > 0)
+                throw e;
+            before = finish([limitFinding(factory, e)], options, true);
+        }
+        const output = run.output;
+        if (before.status === 'rejected' || !output)
+            return { status: 'rejected', before, removed: [] };
+        const out = new io_1.SpillSink(run.temp, run.threshold);
+        run.held.push(out);
+        try {
+            await write(run, output, out, input);
+            await out.close();
+        }
+        catch (e) {
+            await out.close().catch(() => {
+                // The write's failure, handled below, is the one that counts.
+            });
+            if (run.temp.ioError !== undefined)
+                throw run.temp.ioError;
+            if ((0, errors_1.isIoError)(e))
+                throw e;
+            if ((0, errors_1.stopsTree)(e) === 'DEFUSE_LIMIT') {
+                if (depth > 0)
+                    throw e;
+                return refuse(before, limitFinding(factory, e), true);
+            }
+            return refuse(before, factory.make(types_1.OfficeCategory.Processing, types_1.OfficeDetail.VerificationFailed, undefined, { reasons: `write failed: ${String(e?.message ?? e).slice(0, 100)}` }), false);
+        }
+        // The output is checked with the caller's overrides and limits, and the plugins' verdicts in place of the plugins.
+        const verifyOptions = {
+            actionOverrides: options.actionOverrides,
+            scoreWeights: options.scoreWeights,
+            scoreBands: options.scoreBands,
+            tempDir: options.tempDir,
+            memoryThreshold: options.memoryThreshold,
+            limits: { ...options.limits, fileSize: undefined, timeMs: undefined, nestingDepth: undefined },
+        };
+        const outSource = out.source();
+        try {
+            const check = newRun(verifyOptions, depth, deadline, run.kept);
+            let after;
+            try {
+                after = await analyze(check, outSource);
+            }
+            finally {
+                await endRun(check);
+            }
+            const reasons = after.findings.filter(f => f.action !== 'info').map(f => `${f.category}/${f.detail}`);
+            // A check that stopped early verified nothing, even when an override made the finding that stopped it info.
+            if (after.status === 'rejected' && !reasons.length)
+                reasons.push('the output check stopped early');
+            if (after.format !== before.format)
+                reasons.push(`format ${before.format} -> ${after.format}`);
+            if (reasons.length)
+                return refuse(before, factory.make(types_1.OfficeCategory.Processing, types_1.OfficeDetail.VerificationFailed, undefined, { reasons: [...new Set(reasons)].slice(0, 10).join(', ') }), false);
+            await deliver(outSource, sink);
+            return { status: before.status === 'clean' ? 'clean' : 'defused', before, after, removed: before.findings.filter(f => f.action === 'strip') };
+        }
+        finally {
+            await closeSource(outSource);
+        }
+    }
+    catch (e) {
+        // An I/O error inside a nested file fails the upload's run too, instead of counting as a failed plugin.
+        if (depth > 0 && ((0, errors_1.isIoError)(e) || (e !== undefined && e === run.temp.ioError)))
+            throw new errors_1.NestedIoError(e);
+        throw e;
+    }
+    finally {
+        if (input !== source)
+            await closeSource(input);
+        if (depth === 0)
+            await closeSource(source);
+        await endRun(run);
+    }
+}
+/** Defuses Office or OpenDocument bytes. `bytes` holds the output unless the file was rejected. */
+async function disarmOffice(bytes, options = {}) {
+    const sink = (0, io_1.bufferSink)();
+    const result = await disarmOfficeSource((0, io_1.bufferSource)(bytes), sink, options);
+    return result.status === 'rejected' ? result : { ...result, bytes: sink.result() };
 }

package/dist/errors.d.ts

@@ -4,6 +4,23 @@ export declare class TimeLimitError extends Error {
     readonly code = "DEFUSE_LIMIT";
     readonly limit = "time";
 }
+/** A file sits deeper in the upload than `limits.nestingDepth` allows. The code makes every package pass it up. */
+export declare class NestingLimitError extends Error {
+    readonly code = "DEFUSE_LIMIT";
+    readonly limit = "nesting";
+}
+/** An I/O error inside a nested file's own run, carried up so the upload's run fails on it as on its own. */
+export declare class NestedIoError extends Error {
+    readonly code = "DEFUSE_IO";
+    constructor(cause: unknown);
+}
+/**
+ * The code of an error that stops the whole tree of files, from any package: DEFUSE_LIMIT for a time or nesting
+ * limit, DEFUSE_IO for an I/O error. Packages cannot share error classes, so the code alone marks one.
+ */
+export declare function stopsTree(e: unknown): 'DEFUSE_LIMIT' | 'DEFUSE_IO' | undefined;
+/** An error from the operating system, such as EIO or ENOSPC, which says nothing about the file. */
+export declare const isIoError: (e: unknown) => boolean;
 /**
  * A refusal or a limit that stops the run. The engine turns it into the finding it names and rejects the file with
  * no score, whatever the overrides say.

package/dist/errors.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StopError = exports.TimeLimitError = void 0;
+exports.StopError = exports.isIoError = exports.NestedIoError = exports.NestingLimitError = exports.TimeLimitError = void 0;
+exports.stopsTree = stopsTree;
 exports.checkTime = checkTime;
 /** The run passed its deadline. The code makes every package of the family pass it up instead of treating it as one plugin failing. */
 class TimeLimitError extends Error {
@@ -8,6 +9,31 @@ class TimeLimitError extends Error {
     limit = 'time';
 }
 exports.TimeLimitError = TimeLimitError;
+/** A file sits deeper in the upload than `limits.nestingDepth` allows. The code makes every package pass it up. */
+class NestingLimitError extends Error {
+    code = 'DEFUSE_LIMIT';
+    limit = 'nesting';
+}
+exports.NestingLimitError = NestingLimitError;
+/** An I/O error inside a nested file's own run, carried up so the upload's run fails on it as on its own. */
+class NestedIoError extends Error {
+    code = 'DEFUSE_IO';
+    constructor(cause) {
+        super(String(cause?.message ?? cause), { cause });
+    }
+}
+exports.NestedIoError = NestedIoError;
+/**
+ * The code of an error that stops the whole tree of files, from any package: DEFUSE_LIMIT for a time or nesting
+ * limit, DEFUSE_IO for an I/O error. Packages cannot share error classes, so the code alone marks one.
+ */
+function stopsTree(e) {
+    const code = typeof e === 'object' && e !== null ? e.code : undefined;
+    return code === 'DEFUSE_LIMIT' || code === 'DEFUSE_IO' ? code : undefined;
+}
+/** An error from the operating system, such as EIO or ENOSPC, which says nothing about the file. */
+const isIoError = (e) => typeof e?.code === 'string' && /^E[A-Z]+$/.test(e.code);
+exports.isIoError = isIoError;
 /**
  * A refusal or a limit that stops the run. The engine turns it into the finding it names and rejects the file with
  * no score, whatever the overrides say.

package/dist/fields.d.ts

@@ -1,28 +1,35 @@
 import { type RunContext } from './context';
+import type { FieldMarks } from './plan';
 /**
- * Reports a Word field by its code. A field whose name holds the content of an external entity has a type the file
- * does not say, as one whose name another field builds does.
- */
-export declare function evaluateField(ctx: RunContext, location: string, code: string, computed: boolean): void;
-/**
- * Word field codes, followed through nested fields as the text of a document arrives: a field begins, its code
- * comes, a separator starts its result, and it ends. Each format says where those marks are.
+ * Reports a Word field by its code, and tells whether any of its findings strips it. A field whose name holds the
+ * content of an external entity has a type the file does not say, as one whose name another field builds does. A
+ * HYPERLINK field's result is the text the reader sees, and goes with its tooltip into the label check.
  */
+export declare function evaluateField(ctx: RunContext, location: string, code: string, computed: boolean, result?: string): boolean;
 export declare class FieldStack {
     private readonly ctx;
     private readonly location;
+    private readonly onStrip?;
     private readonly stack;
-    constructor(ctx: RunContext, location: string);
+    /**
+     * `onStrip` hears of each field a strip finding names, with the marks the format gave its begin, separator and end,
+     * so the rewrite can find the field again.
+     */
+    constructor(ctx: RunContext, location: string, onStrip?: ((marks: FieldMarks) => void) | undefined);
     /** A field starts. One that starts before its parent's code has a word in it makes that code at run time. */
-    begin(): void;
-    /** A field that is all code, such as OOXML's fldSimple. */
-    simple(code: string): void;
-    separate(): void;
-    end(): void;
+    begin(mark?: number): void;
+    /** A field whose code is given whole, such as OOXML's fldSimple, whose result follows until simpleEnd(). */
+    simpleBegin(code: string, mark?: number): void;
+    simpleEnd(): void;
+    separate(mark?: number): void;
+    end(mark?: number): void;
+    private decide;
     /** Whether a field's code is being read now. */
     get inCode(): boolean;
     /** Text of the innermost field's code. White space before the first word counts for nothing, so no amount of it can push the field's name out. */
     text(t: string): void;
+    /** Text of the innermost field's result, the text the reader sees. */
+    result(t: string): void;
     /** A document can end inside a field. Word still reads the code it has. */
     finish(): void;
     private nest;