@patrickdk77/archive-defuse 0.0.0-stage → 0.1.1

package/dist/pack.js

@@ -0,0 +1,590 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PackError = void 0;
+exports.createArchive = createArchive;
+exports.createArchiveStream = createArchiveStream;
+exports.createArchiveBytes = createArchiveBytes;
+exports.compressTo = compressTo;
+exports.compressStream = compressStream;
+exports.compress = compress;
+// Making archives and compressed files from scratch, for callers who use this package as an archive library: ZIP,
+// tar on its own or compressed, 7z, and the formats that compress one file. The writers are the ones the rewrite uses.
+const node_stream_1 = require("node:stream");
+const bzip2_1 = require("./bzip2");
+const codecs_1 = require("./codecs");
+const crc32_1 = require("./crc32");
+const io_1 = require("./io");
+const lzma_writers_1 = require("./lzma-writers");
+const rules_1 = require("./rules");
+const tar_1 = require("./tar");
+const types_1 = require("./types");
+const zip_writer_1 = require("./zip-writer");
+const zstd_1 = require("./zstd");
+/** Thrown for an entry this package will not write, before anything of the entry is written. */
+class PackError extends Error {
+}
+exports.PackError = PackError;
+const enc = new TextEncoder();
+/** The reading default of `limits.compressionRatio`. */
+const DEFAULT_RATIO = 1000;
+const toBytes = (c) => (typeof c === 'string' ? enc.encode(c) : c);
+/** Bytes that small chunks of an entry are gathered into before they go on. */
+const BATCH = 64 * 1024;
+/** `chunks`, with `check` before each one, so an aborted signal stops a long read. */
+async function* checked(chunks, check) {
+    for await (const c of chunks) {
+        check();
+        yield c;
+    }
+}
+/** The content of an entry as chunks of bytes. */
+async function* chunksOf(data) {
+    if (data === undefined)
+        return;
+    if (typeof data === 'string' || data instanceof Uint8Array) {
+        const b = toBytes(data);
+        if (b.length)
+            yield b;
+        return;
+    }
+    // Small chunks, such as one row of a sheet each, go to the compressor in pieces of BATCH bytes. zlib does the same
+    // work either way, and each write costs as much as a large one.
+    let pending = [];
+    let held = 0;
+    for await (const c of data) {
+        const b = toBytes(c);
+        if (!b.length)
+            continue;
+        if (held === 0 && b.length >= BATCH) {
+            yield b;
+            continue;
+        }
+        pending.push(b);
+        held += b.length;
+        if (held >= BATCH) {
+            yield Buffer.concat(pending, held);
+            pending = [];
+            held = 0;
+        }
+    }
+    if (held)
+        yield Buffer.concat(pending, held);
+}
+/** Why `createArchive` refuses a name, for each name rule of the inspection that changes a name. */
+const REFUSED = {
+    [types_1.ArchiveDetail.Empty]: 'is empty',
+    [types_1.ArchiveDetail.DriveLetter]: 'starts with a drive letter',
+    [types_1.ArchiveDetail.Absolute]: 'is an absolute path',
+    [types_1.ArchiveDetail.Traversal]: 'has a ".." part',
+    [types_1.ArchiveDetail.EmptySegment]: 'has an empty or "." part',
+    [types_1.ArchiveDetail.Backslash]: 'holds a backslash, which Windows reads as a folder separator',
+    [types_1.ArchiveDetail.ControlCharacter]: 'holds a control character or a character that reorders text',
+    [types_1.ArchiveDetail.WindowsReserved]: 'has a part Windows cannot create as written',
+};
+/**
+ * Characters that Windows turns into a slash, a backslash, a colon or a dot when a program that uses the ANSI file
+ * calls converts a name with best fit. Taken from Microsoft's best-fit tables at unicode.org for code pages 874, 932,
+ * 936, 949, 950 and 1250 to 1258. The yen sign is a backslash in code page 932, the won sign in 949, and the acute
+ * accent a slash in 1253.
+ */
+const BEST_FIT = {
+    '\u00a5': '\\',
+    '\u20a9': '\\',
+    '\u2216': '\\',
+    '\uff3c': '\\',
+    '\u00b4': '/',
+    '\u2044': '/',
+    '\u2215': '/',
+    '\uff0f': '/',
+    '\u0589': ':',
+    '\u2236': ':',
+    '\uff1a': ':',
+    '\uff0e': '.',
+};
+const BEST_FIT_CHARS = /[\u00a5\u20a9\u2216\uff3c\u00b4\u2044\u2215\uff0f\u0589\u2236\uff1a\uff0e]/g;
+/** The rules whose break lets an extractor write outside its folder. */
+const ESCAPES = [types_1.ArchiveDetail.DriveLetter, types_1.ArchiveDetail.Absolute, types_1.ArchiveDetail.Traversal];
+/**
+ * Settles an entry's kind and checks its name. The name must pass the inspection's name rules, so the archive passes
+ * this package's own inspection: no ".." part, no absolute path or drive letter, no empty or "." part, no backslash,
+ * control character or part Windows cannot create. It must also not leave its folder once NFKC normalization or
+ * Windows best fit has changed it, as "\uff0e\uff0e/x" becomes "../x".
+ */
+function settle(entry, options, now) {
+    const raw = entry.name;
+    if (typeof raw !== 'string' || raw === '' || raw === '/')
+        throw new PackError('An entry needs a name');
+    if (raw.includes('\0'))
+        throw new PackError(`Entry name ${JSON.stringify(raw)} holds a NUL`);
+    const kind = entry.kind ?? (raw.endsWith('/') ? 'directory' : entry.linkTarget !== undefined ? 'symlink' : 'file');
+    if (kind === 'symlink' && entry.linkTarget === undefined)
+        throw new PackError(`Symbolic link ${JSON.stringify(raw)} needs a linkTarget`);
+    const name = kind === 'directory' ? (raw.endsWith('/') ? raw : `${raw}/`) : raw.replace(/\/+$/, '');
+    for (const detail of (0, rules_1.nameDetails)(name, true)) {
+        const why = REFUSED[detail];
+        if (why)
+            throw new PackError(`Entry name ${JSON.stringify(raw)} ${why}`);
+    }
+    const folds = [
+        [name.normalize('NFKC'), 'NFKC normalization'],
+        [name.replace(BEST_FIT_CHARS, c => BEST_FIT[c]), 'Windows best fit'],
+    ];
+    for (const [folded, how] of folds) {
+        if (folded !== name && (0, rules_1.nameDetails)(folded, true).some(d => ESCAPES.includes(d)))
+            throw new PackError(`Entry name ${JSON.stringify(raw)} leaves its folder after ${how}`);
+    }
+    return { name, kind, entry, mode: (entry.mode ?? (kind === 'directory' ? 0o755 : kind === 'symlink' ? 0o777 : 0o644)) & 0o7777, mtime: entry.mtime ?? options.mtime ?? now };
+}
+/** The content of a settled entry: a file's data, a link's target, or nothing for a folder. */
+async function contentOf(s) {
+    if (s.kind === 'directory')
+        return chunksOf(undefined);
+    if (s.kind === 'symlink')
+        return chunksOf(s.entry.linkTarget);
+    const d = s.entry.data;
+    return chunksOf(typeof d === 'function' ? await d() : d);
+}
+/** Reads an entry's content into memory or a temporary file, counting its CRC-32. */
+async function spillOf(s, temp, threshold, check) {
+    const spill = new io_1.SpillSink(temp, threshold);
+    let crc = 0;
+    try {
+        for await (const c of checked(await contentOf(s), check)) {
+            crc = (0, crc32_1.crc32)(c, crc);
+            await spill.write(c);
+        }
+        await spill.close();
+    }
+    catch (e) {
+        await spill.dispose();
+        throw e;
+    }
+    return { spill, crc };
+}
+const isAscii = (s) => /^[\x20-\x7e]*$/.test(s);
+// ---------------------------------------------------------------------------------------------------------------
+// ZIP
+/** A date as the DOS time and date of a ZIP header, local time, clamped to the years DOS can hold. */
+function dosTime(d) {
+    const year = Math.min(2107, Math.max(1980, d.getFullYear()));
+    return {
+        time: (d.getHours() << 11) | (d.getMinutes() << 5) | (d.getSeconds() >> 1),
+        date: ((year - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+    };
+}
+const ZIP_TYPE_BITS = { file: 0o100000, directory: 0o040000, symlink: 0o120000 };
+async function writeZipEntries(entries, sink, options, temp, check) {
+    const out = new zip_writer_1.ZipOutput(sink);
+    const threshold = options.memoryThreshold ?? 8 * 1024 * 1024;
+    const level = options.level ?? 6;
+    for await (const s of entries) {
+        const { time, date } = dosTime(s.mtime);
+        const info = {
+            name: enc.encode(s.name),
+            flags: isAscii(s.name) ? 0 : 0x0800,
+            method: 0,
+            versionNeeded: s.kind === 'directory' ? 20 : 10,
+            versionMadeBy: (3 << 8) | 30,
+            externalAttr: (((ZIP_TYPE_BITS[s.kind] | s.mode) << 16) >>> 0) | (s.kind === 'directory' ? 0x10 : 0),
+            internalAttr: 0,
+            time,
+            date,
+            crc: 0,
+            compressedSize: 0,
+            size: 0,
+            extras: new Uint8Array(0),
+            comment: new Uint8Array(0),
+        };
+        if (s.kind === 'directory') {
+            await out.entry(info, () => chunksOf(undefined), s.name);
+            continue;
+        }
+        if (options.streaming) {
+            await streamZipEntry(out, s, info, level, check);
+            continue;
+        }
+        // The content is read once, into memory or a temporary file, and deflated from there, so it can be stored instead
+        // when deflate gains nothing or passes the ratio limit.
+        const { spill: raw, crc } = await spillOf(s, temp, threshold, check);
+        const deflated = new io_1.SpillSink(temp, threshold);
+        try {
+            let stored = s.kind === 'symlink' || s.entry.store === true || level === 0 || raw.length === 0;
+            if (!stored) {
+                for await (const c of (0, codecs_1.deflateRaw)(checked(raw.read(), check), level))
+                    await deflated.write(c);
+                await deflated.close();
+                stored = deflated.length >= raw.length || (0, lzma_writers_1.passesRatio)(raw.length, deflated.length, options.ratioLimit ?? DEFAULT_RATIO);
+            }
+            info.method = stored ? 0 : 8;
+            info.versionNeeded = stored ? 10 : 20;
+            info.crc = crc;
+            info.size = raw.length;
+            info.compressedSize = stored ? raw.length : deflated.length;
+            await out.entry(info, () => checked(stored ? raw.read() : deflated.read(), check), s.name);
+        }
+        finally {
+            await deflated.dispose();
+            await raw.dispose();
+        }
+    }
+    await out.end(enc.encode(options.comment ?? ''));
+}
+/**
+ * Writes one entry of a streaming ZIP archive. A file is deflated as its data arrives and gets a data descriptor; at
+ * level 0, deflate writes stored blocks. An empty file is stored with its sizes. A link's target and a file the caller
+ * stores are held in memory, so their headers carry their sizes, since a stored entry with a data descriptor is how a
+ * second, hidden entry gets past a reader of the central directory.
+ */
+async function streamZipEntry(out, s, info, level, check) {
+    const it = checked(await contentOf(s), check)[Symbol.asyncIterator]();
+    let first;
+    try {
+        first = await it.next();
+    }
+    catch (e) {
+        await it.return?.(undefined);
+        throw e;
+    }
+    if (s.kind === 'symlink' || s.entry.store === true || first.done) {
+        const parts = [];
+        let crc = 0;
+        try {
+            for (let r = first; !r.done; r = await it.next()) {
+                crc = (0, crc32_1.crc32)(r.value, crc);
+                parts.push(r.value);
+            }
+        }
+        finally {
+            await it.return?.(undefined);
+        }
+        const data = Buffer.concat(parts);
+        Object.assign(info, { method: 0, versionNeeded: 10, crc, size: data.length, compressedSize: data.length });
+        await out.entry(info, () => chunksOf(data), s.name);
+        return;
+    }
+    let crc = 0;
+    let size = 0;
+    const raw = async function* () {
+        try {
+            for (let r = first; !r.done; r = await it.next()) {
+                crc = (0, crc32_1.crc32)(r.value, crc);
+                size += r.value.length;
+                yield r.value;
+            }
+        }
+        finally {
+            await it.return?.(undefined);
+        }
+    };
+    Object.assign(info, { method: 8, versionNeeded: 20 });
+    await out.streamEntry(info, (0, codecs_1.deflateRaw)(raw(), level), () => ({ crc, size }));
+}
+// ---------------------------------------------------------------------------------------------------------------
+// tar
+const TAR_TYPES = { file: '0', directory: '5', symlink: '2' };
+async function* tarChunks(entries, options, temp, check) {
+    const threshold = options.memoryThreshold ?? 8 * 1024 * 1024;
+    let written = 0;
+    const pad = (n) => Buffer.alloc((tar_1.BLOCK - (n % tar_1.BLOCK)) % tar_1.BLOCK);
+    for await (const s of entries) {
+        const { spill } = s.kind === 'file' ? await spillOf(s, temp, threshold, check) : { spill: undefined };
+        try {
+            const size = spill?.length ?? 0;
+            const link = s.kind === 'symlink' ? (s.entry.linkTarget ?? '') : '';
+            const mtime = Math.floor(s.mtime.getTime() / 1000);
+            // What the ustar header cannot hold goes in a pax header before it.
+            const records = [];
+            const parts = (0, tar_1.split)(s.name);
+            if (!parts)
+                records.push((0, tar_1.paxRecord)('path', Buffer.from(s.name, 'utf8')));
+            const linkFits = isAscii(link) && link.length <= 100;
+            if (!linkFits)
+                records.push((0, tar_1.paxRecord)('linkpath', Buffer.from(link, 'utf8')));
+            if (size > 0o77777777777)
+                records.push((0, tar_1.paxRecord)('size', Buffer.from(String(size))));
+            const timeFits = mtime >= 0 && mtime <= 0o77777777777;
+            if (!timeFits)
+                records.push((0, tar_1.paxRecord)('mtime', Buffer.from(String(mtime))));
+            if (records.length) {
+                const body = Buffer.concat(records);
+                const h = (0, tar_1.header)({
+                    name: Buffer.from('././@PaxHeader'),
+                    mode: 0o644,
+                    uid: 0,
+                    gid: 0,
+                    size: body.length,
+                    mtime: 0,
+                    typeflag: 'x',
+                    linkname: Buffer.alloc(0),
+                    uname: '',
+                    gname: '',
+                    prefix: Buffer.alloc(0),
+                    devmajor: 0,
+                    devminor: 0,
+                });
+                yield h;
+                yield body;
+                yield pad(body.length);
+                written += h.length + body.length + pad(body.length).length;
+            }
+            const h = (0, tar_1.header)({
+                name: parts?.name ?? (0, tar_1.asciiFallback)(s.name),
+                prefix: parts?.prefix ?? Buffer.alloc(0),
+                mode: s.mode,
+                uid: 0,
+                gid: 0,
+                size: size > 0o77777777777 ? 0 : size,
+                mtime: timeFits ? mtime : 0,
+                typeflag: TAR_TYPES[s.kind],
+                linkname: linkFits ? Buffer.from(link, 'latin1') : (0, tar_1.asciiFallback)(link),
+                uname: '',
+                gname: '',
+                devmajor: 0,
+                devminor: 0,
+            });
+            yield h;
+            written += h.length;
+            if (spill) {
+                yield* checked(spill.read(), check);
+                const p = pad(size);
+                if (p.length)
+                    yield p;
+                written += size + p.length;
+            }
+        }
+        finally {
+            await spill?.dispose();
+        }
+    }
+    const end = Buffer.alloc(2 * tar_1.BLOCK);
+    yield end;
+    written += end.length;
+    const tail = (tar_1.RECORD - (written % tar_1.RECORD)) % tar_1.RECORD;
+    if (tail)
+        yield Buffer.alloc(tail);
+}
+// ---------------------------------------------------------------------------------------------------------------
+// 7z
+/** A date as a Windows FILETIME: 100-nanosecond intervals since 1601, little-endian. */
+function fileTime(d) {
+    const t = BigInt(d.getTime() + 11_644_473_600_000) * 10000n;
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(t < 0n ? 0n : t);
+    return b;
+}
+async function writeSevenEntries(entries, sink, options, temp, check) {
+    const threshold = options.memoryThreshold ?? 8 * 1024 * 1024;
+    const spills = [];
+    const out = [];
+    try {
+        // 7z writes its header after the data, from every entry, so each entry is read before any is written.
+        let held = 0;
+        for await (const s of entries) {
+            const dir = s.kind === 'directory';
+            let content;
+            if (!dir) {
+                const { spill } = await spillOf(s, temp, Math.max(0, threshold - held), check);
+                spills.push(spill);
+                if (!spill.spilled)
+                    held += spill.length;
+                content = { size: spill.length, chunks: () => spill.read() };
+            }
+            const typeBits = dir ? 0o040000 : s.kind === 'symlink' ? 0o120000 : 0o100000;
+            // The Unix mode sits in the high 16 bits, with 0x8000 to say it is there, as p7zip writes it.
+            const attrib = (((typeBits | s.mode) << 16) | 0x8000 | (dir ? 0x10 : 0x20)) >>> 0;
+            out.push({ name: dir ? s.name.slice(0, -1) : s.name, dir, attrib, mtime: fileTime(s.mtime), content });
+        }
+        await (0, lzma_writers_1.writeSevenZip)(out, sink, temp, threshold, check, options.ratioLimit ?? DEFAULT_RATIO);
+    }
+    finally {
+        for (const s of spills)
+            await s.dispose();
+    }
+}
+// ---------------------------------------------------------------------------------------------------------------
+// One compressed stream
+/** A gzip member around raw deflate, with the CRC-32 and size after it. */
+async function* gzipOf(chunks, level, mtime) {
+    const head = Buffer.from([0x1f, 0x8b, 8, 0, 0, 0, 0, 0, 0, 255]);
+    head.writeUInt32LE(Math.max(0, Math.min(0xffffffff, Math.floor(mtime.getTime() / 1000))), 4);
+    yield head;
+    let crc = 0;
+    let size = 0;
+    async function* tally() {
+        for await (const c of chunks) {
+            crc = (0, crc32_1.crc32)(c, crc);
+            size += c.length;
+            yield c;
+        }
+    }
+    yield* (0, codecs_1.deflateRaw)(tally(), level);
+    const tail = Buffer.alloc(8);
+    tail.writeUInt32LE(crc >>> 0, 0);
+    tail.writeUInt32LE(size % 2 ** 32, 4);
+    yield tail;
+}
+/** xz and .lzma need the content by offset, or its size first, so it is read into memory or a temporary file. */
+async function* lzmaOf(format, chunks, options, temp, check) {
+    const spill = new io_1.SpillSink(temp, options.memoryThreshold ?? 8 * 1024 * 1024);
+    try {
+        for await (const c of checked(chunks, check))
+            await spill.write(c);
+        await spill.close();
+        const source = spill.length ? spill.source() : undefined;
+        // The writers write to a sink, so their output goes to memory or a temporary file and then out.
+        const encoded = new io_1.SpillSink(temp, options.memoryThreshold ?? 8 * 1024 * 1024);
+        try {
+            try {
+                if (format === 'xz')
+                    await (0, lzma_writers_1.writeXz)(source, 4, encoded, check);
+                else
+                    await (0, lzma_writers_1.writeAlone)(source, encoded, check);
+            }
+            finally {
+                await source?.close?.();
+            }
+            await encoded.close();
+            yield* checked(encoded.read(), check);
+        }
+        finally {
+            await encoded.dispose();
+        }
+    }
+    finally {
+        await spill.dispose();
+    }
+}
+function compressChunks(format, input, options, temp, now, check) {
+    const chunks = checked(input, check);
+    switch (format) {
+        case 'gzip':
+            return gzipOf(chunks, options.level ?? 6, options.mtime ?? now);
+        case 'bzip2':
+            return (0, bzip2_1.bzip2)(chunks, options.level ?? 9);
+        case 'zstd':
+            return (0, zstd_1.zstdEncode)(chunks);
+        case 'brotli':
+            return (0, codecs_1.brotliEncode)(chunks);
+        case 'xz':
+        case 'lzma':
+            return lzmaOf(format, chunks, options, temp, check);
+        default:
+            throw new PackError(`Unknown format ${String(format)}`);
+    }
+}
+// ---------------------------------------------------------------------------------------------------------------
+// The calls
+const ARCHIVE_FORMATS = new Set(['zip', 'tar', 'tar.gz', 'tar.bz2', 'tar.zst', 'tar.xz', '7z']);
+const TAR_COMPRESSION = { 'tar.gz': 'gzip', 'tar.bz2': 'bzip2', 'tar.zst': 'zstd', 'tar.xz': 'xz' };
+/** Copies chunks to the sink, then closes it. On failure it aborts the sink, so a partial output never looks whole. */
+async function deliver(produce, sink) {
+    try {
+        await produce();
+    }
+    catch (e) {
+        try {
+            await sink.abort?.(e);
+        }
+        catch {
+            // The write's error is the one to report.
+        }
+        throw e;
+    }
+    await sink.close();
+}
+/**
+ * Writes an archive of `entries`, in their order, to `sink`, then closes it. Entries can come as a list or as an async
+ * iterable, and each file's content as bytes, text or a stream. When anything fails, such as an entry's stream, the
+ * sink is aborted instead of closed and the error is thrown.
+ */
+async function createArchive(format, entries, sink, options = {}) {
+    if (!ARCHIVE_FORMATS.has(format))
+        throw new PackError(`Unknown archive format ${String(format)}`);
+    // tar needs each entry's size before its data, and 7z writes its header from every entry after the data.
+    if (options.streaming && format !== 'zip')
+        throw new PackError(`streaming writes ZIP archives only, not ${format}`);
+    const now = new Date();
+    const temp = new io_1.TempDir(options.tempDir);
+    const check = () => options.signal?.throwIfAborted();
+    async function* settled() {
+        for await (const e of entries) {
+            check();
+            yield settle(e, options, now);
+        }
+    }
+    try {
+        await deliver(async () => {
+            check();
+            if (format === 'zip')
+                return writeZipEntries(settled(), sink, options, temp, check);
+            if (format === '7z')
+                return writeSevenEntries(settled(), sink, options, temp, check);
+            const tar = tarChunks(settled(), options, temp, check);
+            const method = TAR_COMPRESSION[format];
+            for await (const c of method ? compressChunks(method, tar, options, temp, now, check) : tar)
+                await sink.write(c);
+        }, sink);
+    }
+    finally {
+        await temp.cleanup();
+    }
+}
+/**
+ * Runs `write` into a Node Readable. An error destroys the stream, so a consumer never takes a partial output as whole.
+ * A consumer that destroys the stream before its end, or the caller's signal, stops the work.
+ */
+function readableOf(write, signal) {
+    const out = new node_stream_1.PassThrough();
+    const controller = new AbortController();
+    const stop = () => controller.abort(signal?.reason);
+    if (signal?.aborted)
+        stop();
+    else
+        signal?.addEventListener('abort', stop, { once: true });
+    out.on('close', () => {
+        if (!controller.signal.aborted)
+            controller.abort(out.errored ?? new Error('The output stream closed before all data was written'));
+    });
+    write((0, io_1.writableSink)(out), controller.signal)
+        .catch(e => {
+        if (!out.destroyed)
+            out.destroy(e instanceof Error ? e : new Error(String(e)));
+    })
+        .finally(() => signal?.removeEventListener('abort', stop));
+    return out;
+}
+/** `createArchive` as a Node Readable, to pipe to a file, an HTTP response or an upload. */
+function createArchiveStream(format, entries, options = {}) {
+    return readableOf((sink, signal) => createArchive(format, entries, sink, { ...options, signal }), options.signal);
+}
+/** `createArchive` into memory. */
+async function createArchiveBytes(format, entries, options = {}) {
+    const sink = (0, io_1.bufferSink)();
+    await createArchive(format, entries, sink, options);
+    return sink.result();
+}
+/** Compresses `data` as one stream of `format` to `sink`, then closes it. */
+async function compressTo(format, data, sink, options = {}) {
+    const temp = new io_1.TempDir(options.tempDir);
+    const check = () => options.signal?.throwIfAborted();
+    try {
+        await deliver(async () => {
+            check();
+            for await (const c of compressChunks(format, chunksOf(data), options, temp, new Date(), check))
+                await sink.write(c);
+        }, sink);
+    }
+    finally {
+        await temp.cleanup();
+    }
+}
+/** `compressTo` as a Node Readable. */
+function compressStream(format, data, options = {}) {
+    return readableOf((sink, signal) => compressTo(format, data, sink, { ...options, signal }), options.signal);
+}
+/** `compressTo` into memory. */
+async function compress(format, data, options = {}) {
+    const sink = (0, io_1.bufferSink)();
+    await compressTo(format, data, sink, options);
+    return sink.result();
+}

package/dist/plugins.d.ts

@@ -0,0 +1,13 @@
+import type { ArchiveOptions, ContainedFilePlugin } from './types';
+/**
+ * Keeps contained files unchanged by type or by name, as pdf-defuse's passThrough does. An entry with a "/" is a MIME
+ * type. Any other entry, such as ".csv" or "csv", is a file name extension.
+ */
+export declare function passThrough(types: string[]): ContainedFilePlugin;
+/**
+ * Defuses archives inside other files, with `options` when given. Without them, it takes the options of the
+ * archive-defuse run that found the file, or none when another package found it. It accepts a file by its content,
+ * whatever its name says. `limits.nestingDepth` applies to the depth in the context. The archive'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 archivePlugin(options?: ArchiveOptions): ContainedFilePlugin;

package/dist/plugins.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.passThrough = passThrough;
+exports.archivePlugin = archivePlugin;
+const detect_1 = require("./detect");
+const engine_1 = require("./engine");
+const score_1 = require("./score");
+const sniff_1 = require("./sniff");
+/**
+ * Keeps contained files unchanged by type or by name, as pdf-defuse's passThrough does. An entry with a "/" is a MIME
+ * type. Any other entry, such as ".csv" or "csv", is a file name extension.
+ */
+function passThrough(types) {
+    const set = new Set(types.filter(t => t.includes('/')).map(t => t.toLowerCase()));
+    const exts = new Set(types.filter(t => !t.includes('/')).map(t => t.trim().toLowerCase().replace(/^\./, '')));
+    return {
+        kind: 'file',
+        name: `passThrough(${types.join(',')})`,
+        // Matches on type alone. Whether the content, the declared type and the name agree is the type check's finding.
+        accepts: f => {
+            const ext = (0, sniff_1.extensionOf)(f.name);
+            if (ext !== undefined && exts.has(ext))
+                return true;
+            return [f.sniffedType, f.declaredType, (0, sniff_1.typeFromName)(f.name)].some(t => t !== undefined && set.has(t.toLowerCase().split(';')[0].trim()));
+        },
+        process: async () => 'passed',
+    };
+}
+/**
+ * Defuses archives inside other files, with `options` when given. Without them, it takes the options of the
+ * archive-defuse run that found the file, or none when another package found it. It accepts a file by its content,
+ * whatever its name says. `limits.nestingDepth` applies to the depth in the context. The archive's findings go into
+ * the containing file's report, and its output's findings into the output's report, each with its `weight`.
+ */
+function archivePlugin(options) {
+    return {
+        kind: 'file',
+        name: 'archive',
+        // It takes what detectArchive claims, which is what the inspection reads, Brotli included: the content decides.
+        accepts: async (f) => (await (0, detect_1.detectArchiveSource)(f.source, { name: f.name, declaredType: f.declaredType })) !== undefined,
+        async process(file, sink, context) {
+            const run = options ?? context[engine_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 archive, 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/rules.d.ts

@@ -0,0 +1,25 @@
+import type { FindingFactory } from './findings';
+import type { Entry } from './model';
+import { ArchiveCategory as C, ArchiveDetail as D } from './types';
+/** What the rules decided about one entry. */
+export interface Decision {
+    remove: boolean;
+    /** The name to write. */
+    name: string;
+    mode?: number;
+    dropCapabilities: boolean;
+    /** For a hard link: the index of the entry it links to, when that is an entry before it. */
+    linkIndex?: number;
+}
+export type Emit = (category: C, detail: D, e: Entry, data?: Record<string, string | number>) => void;
+/**
+ * The name rules a name breaks, in the order they report. `applyRules` reports these, and `createArchive` refuses a
+ * name that breaks any but TOO_LONG. A ".." part is TRAVERSAL's alone, and empty parts at the start belong to an
+ * absolute or UNC path, which ABSOLUTE reports.
+ */
+export declare function nameDetails(name: string, backslashIsSeparator: boolean): D[];
+/** Runs the rules over the entries of an archive. Single-file formats with no name skip the name rules. */
+export declare function applyRules(entries: Entry[], factory: FindingFactory, emit: Emit, options: {
+    names: boolean;
+    backslashIsSeparator: boolean;
+}): Decision[];