@patrickdk77/office-defuse 0.1.0 → 0.2.0

package/dist/cli.js

@@ -0,0 +1,357 @@
+#!/usr/bin/env node
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const fs = __importStar(require("node:fs"));
+const fsp = __importStar(require("node:fs/promises"));
+const path = __importStar(require("node:path"));
+const promises_1 = require("node:stream/promises");
+const node_url_1 = require("node:url");
+const engine_1 = require("./engine");
+const errors_1 = require("./errors");
+const io_1 = require("./io");
+const plugins_1 = require("./plugins");
+const USAGE = `Usage:
+  office-defuse inspect <file> [options]
+  office-defuse defuse <in> <out> [options]
+
+Options:
+  --password-file <path>   read passwords from a file, one per line; OFFICE_DEFUSE_PASSWORD holds one
+  --plugin <module>        load file plugins from a file or an installed package, repeatable
+  --config <module>        load a whole options object, repeatable; the other options apply on top
+  --defuse-embedded-office defuse Office files inside the file with office-defuse and keep them
+  --limit <name>=<value>   fileSize, entries, decompressedBytes, totalDecompressedBytes, xmlDepth,
+                           xmlTokenSize, xmlEntityDepth, xmlEntityExpansions, xmlEntitySize, rtfDepth,
+                           nestingDepth, timeMs; sizes accept kb, mb, gb
+  --json                   print the result as JSON
+
+Use - for stdin or stdout.
+Exit codes: 0 clean, 1 stripped or strippable, 2 rejected, 3 usage or I/O error.`;
+class UsageError extends Error {
+}
+const SIZES = new Set(['fileSize', 'decompressedBytes', 'totalDecompressedBytes']);
+const COUNTS = new Set(['entries', 'xmlDepth', 'xmlTokenSize', 'xmlEntityDepth', 'xmlEntityExpansions', 'xmlEntitySize', 'rtfDepth', 'nestingDepth', 'timeMs']);
+function parseSize(v) {
+    const m = /^(\d+(?:\.\d+)?)\s*(b|kb|k|mb|m|gb|g)?$/i.exec(v.trim());
+    if (!m)
+        throw new UsageError(`Bad size "${v}"`);
+    const mult = { b: 1, k: 1024, kb: 1024, m: 1024 ** 2, mb: 1024 ** 2, g: 1024 ** 3, gb: 1024 ** 3 };
+    return Math.round(Number(m[1]) * mult[(m[2] ?? 'b').toLowerCase()]);
+}
+// A real dynamic import. TypeScript would compile import() to require() for CommonJS output,
+// and require() cannot load ES modules or file URLs.
+const dynamicImport = new Function('specifier', 'return import(specifier)');
+/** Reads `key` from `v` the way `v?.[key]` does, for a value whose shape is not known. */
+function prop(v, key) {
+    return (typeof v === 'object' && v !== null) || typeof v === 'function' ? v[key] : undefined;
+}
+const isObject = (v) => typeof v === 'object' && v !== null;
+async function loadModule(spec) {
+    // A bare name ending in .js can be a file in the working directory or a package with that name. The file wins.
+    const looksLikePath = spec.startsWith('.') || path.isAbsolute(spec) || (/\.(c|m)?js$/.test(spec) && fs.statSync(spec, { throwIfNoEntry: false })?.isFile() === true);
+    let resolved;
+    if (looksLikePath)
+        resolved = path.resolve(process.cwd(), spec);
+    else {
+        try {
+            resolved = require.resolve(spec, { paths: [process.cwd()] });
+        }
+        catch (e) {
+            // require.resolve applies only the "require" condition, so a package that exports only "import" ends up here.
+            if (e.code !== 'ERR_PACKAGE_PATH_NOT_EXPORTED')
+                throw e;
+            const name = spec
+                .split('/')
+                .slice(0, spec.startsWith('@') ? 2 : 1)
+                .join('/');
+            const subpath = `.${spec.slice(name.length)}`;
+            for (let dir = process.cwd(); resolved === undefined; dir = path.dirname(dir)) {
+                const pkg = path.join(dir, 'node_modules', name);
+                if (fs.existsSync(path.join(pkg, 'package.json'))) {
+                    const exp = JSON.parse(fs.readFileSync(path.join(pkg, 'package.json'), 'utf8')).exports;
+                    const isMap = isObject(exp) && Object.keys(exp).some(k => k.startsWith('.'));
+                    let target;
+                    let match;
+                    if (!isMap)
+                        target = subpath === '.' ? exp : undefined;
+                    else if (Object.hasOwn(exp, subpath) && !subpath.includes('*'))
+                        target = exp[subpath];
+                    else {
+                        // A pattern key holds one "*". Node prefers the longest text before the "*", then the longest key, and puts
+                        // what the "*" matched into the target.
+                        let best = '';
+                        for (const k of Object.keys(exp)) {
+                            const star = k.indexOf('*');
+                            const trailer = k.slice(star + 1);
+                            if (star < 0 || trailer.includes('*') || !subpath.startsWith(k.slice(0, star)) || subpath.length === star)
+                                continue;
+                            if (trailer && (!subpath.endsWith(trailer) || subpath.length < k.length))
+                                continue;
+                            if (!best || star > best.indexOf('*') || (star === best.indexOf('*') && k.length > best.length))
+                                best = k;
+                        }
+                        if (best) {
+                            target = exp[best];
+                            match = subpath.slice(best.indexOf('*'), subpath.length - (best.length - best.indexOf('*') - 1));
+                            // Node refuses a match that would step outside the pattern's directory.
+                            if (match.split(/[/\\]/).some(s => s === '' || s === '.' || s === '..' || s.toLowerCase() === 'node_modules'))
+                                throw e;
+                        }
+                    }
+                    // Node takes the first condition it supports, in the order the package lists them.
+                    while (isObject(target) && !Array.isArray(target))
+                        target = target[Object.keys(target).find(k => k === 'node' || k === 'import' || k === 'default') ?? ''];
+                    if (typeof target !== 'string')
+                        throw e;
+                    resolved = path.resolve(pkg, match === undefined ? target : target.replaceAll('*', match));
+                }
+                else if (path.dirname(dir) === dir)
+                    throw e;
+            }
+        }
+    }
+    return dynamicImport((0, node_url_1.pathToFileURL)(resolved).href);
+}
+function pluginsFrom(mod) {
+    // import() gives a CommonJS module a default export holding module.exports, so the named exports come first.
+    const value = prop(mod, 'plugins') ?? prop(prop(mod, 'default'), 'plugins') ?? prop(mod, 'plugin') ?? prop(prop(mod, 'default'), 'plugin') ?? prop(mod, 'default');
+    const list = Array.isArray(value) ? value : [value];
+    for (const p of list)
+        if (!p || prop(p, 'kind') !== 'file')
+            throw new UsageError('A plugin module must export plugins with kind "file"');
+    // The loop above checked each entry's kind, which is as far as a plugin's shape can be checked here.
+    return list;
+}
+async function parse(argv) {
+    const [command, ...rest] = argv;
+    if (command !== 'inspect' && command !== 'defuse')
+        throw new UsageError(command ? `Unknown command "${command}"` : 'No command');
+    const positional = [];
+    // Every --config module goes in first and the flags apply on top, wherever they sit on the command line.
+    const options = {};
+    const ordered = [];
+    const limits = {};
+    let password = process.env.OFFICE_DEFUSE_PASSWORD;
+    let json = false;
+    for (let i = 0; i < rest.length; i++) {
+        const a = rest[i];
+        const next = () => {
+            const v = rest[++i];
+            if (v === undefined)
+                throw new UsageError(`${a} needs a value`);
+            return v;
+        };
+        switch (a) {
+            case '--password-file':
+                // A blank line holds no password, so it adds nothing to the list.
+                password = (await fsp.readFile(next(), 'utf8'))
+                    .split('\n')
+                    .map(line => line.replace(/\r$/, ''))
+                    .filter(line => line !== '');
+                break;
+            case '--plugin':
+                ordered.push(...pluginsFrom(await loadModule(next())));
+                break;
+            case '--config': {
+                const mod = await loadModule(next());
+                // The module's shape is the caller's to get right, as OfficeOptions documents it.
+                const cfg = (prop(mod, 'default') ?? mod);
+                // Modules combine: plugin lists join in order and limits merge. For any other option the later module wins.
+                Object.assign(options, cfg, {
+                    filePlugins: [...(options.filePlugins ?? []), ...(cfg.filePlugins ?? [])],
+                    limits: { ...options.limits, ...cfg.limits },
+                });
+                break;
+            }
+            case '--defuse-embedded-office':
+                ordered.push((0, plugins_1.officePlugin)());
+                break;
+            case '--limit': {
+                const [name, value] = next().split('=');
+                if (value === undefined)
+                    throw new UsageError('--limit expects name=value');
+                if (SIZES.has(name))
+                    limits[name] = parseSize(value);
+                else if (COUNTS.has(name)) {
+                    // Number('abc') is NaN, and no comparison with NaN is true, so the limit would never apply.
+                    if (!/^\d+$/.test(value.trim()))
+                        throw new UsageError(`Bad value for ${name}: "${value}"`);
+                    limits[name] = Number(value);
+                }
+                else
+                    throw new UsageError(`Unknown limit "${name}"`);
+                break;
+            }
+            case '--json':
+                json = true;
+                break;
+            default:
+                if (a === '--password' || a.startsWith('--password='))
+                    throw new UsageError('Pass the password with --password-file or OFFICE_DEFUSE_PASSWORD, not on the command line');
+                // What follows "=" can be a secret typed in the wrong place, and stderr often ends up in a log.
+                if (a.startsWith('--'))
+                    throw new UsageError(`Unknown option ${a.replace(/=.*/s, '=...')}`);
+                positional.push(a);
+        }
+    }
+    if (ordered.length)
+        options.filePlugins = [...(options.filePlugins ?? []), ...ordered];
+    if (Object.keys(limits).length)
+        options.limits = { ...(options.limits ?? {}), ...limits };
+    if (password !== undefined)
+        options.password = password;
+    return { command, positional, options, json };
+}
+/**
+ * The input as a source. stdin is copied to a temporary file first. The copy stops one byte past `fileSize`, so the
+ * engine rejects the upload as too large without the rest being read, and at the deadline, where the source then
+ * fails the run for time.
+ */
+async function inputSource(p, tempDir, fileSize, deadline) {
+    if (p !== '-') {
+        return {
+            source: (0, io_1.fileSource)(p),
+            cleanup: async () => {
+                // The caller's own file stays.
+            },
+        };
+    }
+    const temp = new io_1.TempDir(tempDir);
+    try {
+        const file = await temp.file('.office');
+        let room = (fileSize ?? Number.POSITIVE_INFINITY) + 1;
+        try {
+            await (0, promises_1.pipeline)(process.stdin, async function* (chunks) {
+                for await (const c of chunks) {
+                    yield c.subarray(0, room);
+                    room -= c.length;
+                    if (room <= 0)
+                        return;
+                }
+            }, fs.createWriteStream(file), { signal: deadline === undefined ? undefined : AbortSignal.timeout(Math.max(0, deadline - Date.now())) });
+        }
+        catch (e) {
+            if (e.name !== 'AbortError')
+                throw e;
+            const late = () => Promise.reject(new errors_1.TimeLimitError('Time limit exceeded'));
+            return { source: { size: late, read: late }, cleanup: () => temp.cleanup() };
+        }
+        return { source: (0, io_1.fileSource)(file), cleanup: () => temp.cleanup() };
+    }
+    catch (e) {
+        await temp.cleanup();
+        throw e;
+    }
+}
+/** Writes a control character as a JSON escape, since text from the file could otherwise drive the terminal. */
+const escaped = (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`;
+function report(label, i) {
+    const lines = [`${label}: ${i.status}, risk ${i.risk}${i.score === null ? '' : ` (score ${i.score})`}, ${i.format ? i.format.toUpperCase() : '?'}`];
+    for (const f of i.findings)
+        lines.push(`  ${f.action.padEnd(6)} ${f.category}/${f.detail}${f.location ? ` [${f.location}]` : ''}: ${f.description}`);
+    // A location can hold a part name, a field code or a link from the file. A line break in one would print a line of
+    // its own.
+    return lines.map(l => l.replace(/\p{Cc}/gu, escaped)).join('\n');
+}
+async function main(argv) {
+    let parsed;
+    try {
+        parsed = await parse(argv);
+    }
+    catch (e) {
+        process.stderr.write(`${e.message}\n\n${USAGE}\n`);
+        return 3;
+    }
+    const { command, positional, options, json } = parsed;
+    try {
+        if (command === 'inspect' && positional.length !== 1)
+            throw new UsageError('inspect takes one file');
+        if (command === 'defuse' && positional.length !== 2)
+            throw new UsageError('defuse takes an input and an output');
+        const toStdout = command === 'defuse' && positional[1] === '-';
+        if (command === 'defuse' && positional[0] !== '-' && !toStdout) {
+            // A failed write deletes the partial output, which here would be the only copy of the input.
+            const [a, b] = await Promise.all([fsp.stat(positional[0]), fsp.stat(positional[1]).catch(() => undefined)]);
+            if (b && a.dev === b.dev && a.ino === b.ino)
+                throw new UsageError('The input and the output are the same file');
+        }
+        // Reading stdin counts toward the time limit, so the run gets what is left of it.
+        const deadline = options.limits?.timeMs === undefined ? undefined : Date.now() + options.limits.timeMs;
+        const input = await inputSource(positional[0], options.tempDir, options.limits?.fileSize, deadline);
+        const runOptions = deadline === undefined ? options : { ...options, limits: { ...options.limits, timeMs: deadline - Date.now() } };
+        let text;
+        let code;
+        try {
+            if (command === 'inspect') {
+                const r = await (0, engine_1.inspectOfficeSource)(input.source, runOptions);
+                text = json ? JSON.stringify(r, null, 2) : report('inspection', r);
+                code = r.status === 'clean' ? 0 : r.status === 'strippable' ? 1 : 2;
+            }
+            else {
+                const r = await (0, engine_1.disarmOfficeSource)(input.source, toStdout ? (0, io_1.writableSink)(process.stdout) : (0, io_1.fileSink)(positional[1]), runOptions);
+                text = json ? JSON.stringify(r, null, 2) : [`result: ${r.status}`, report('before', r.before), ...(r.after && r.status === 'defused' ? [report('after', r.after)] : [])].join('\n');
+                code = r.status === 'clean' ? 0 : r.status === 'defused' ? 1 : 2;
+            }
+        }
+        finally {
+            await input.source.close?.();
+            await input.cleanup();
+        }
+        // JSON.stringify escapes C0 controls but not DEL or the C1 range.
+        if (json)
+            text = text.replace(/[\u007f-\u009f]/g, escaped);
+        // The report shares stdout only when the file goes elsewhere. A report nobody can read is an I/O error.
+        const out = toStdout ? process.stderr : process.stdout;
+        await new Promise((resolve, reject) => out.write(`${text}\n`, e => (e ? reject(e) : resolve())));
+        return code;
+    }
+    catch (e) {
+        process.stderr.write(`${e instanceof UsageError ? `${e.message}\n\n${USAGE}` : `Error: ${e.message}`}\n`);
+        return 3;
+    }
+}
+if (require.main === module) {
+    // main() learns of a failed write from its callback. Node emits the failure as an 'error' event as well, which
+    // with no listener would end the process with exit code 1.
+    for (const stream of [process.stdout, process.stderr]) {
+        stream.on('error', () => {
+            process.exitCode = 3;
+        });
+    }
+    main(process.argv.slice(2)).then(code => {
+        process.exitCode = code;
+    });
+}

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;
+}