@patrickdk77/archive-defuse 0.0.0-stage → 0.1.0

package/dist/checks.js

@@ -0,0 +1,123 @@
+"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.CHECK_SHA256 = exports.CHECK_CRC64 = exports.CHECK_CRC32 = exports.CHECK_NONE = exports.Crc64 = void 0;
+exports.checkSize = checkSize;
+exports.checkName = checkName;
+exports.makeCheck = makeCheck;
+const crypto = __importStar(require("node:crypto"));
+const crc32_1 = require("./crc32");
+// CRC-64 with the ECMA-182 polynomial, reflected, as xz uses it. Node has no CRC-64, so this table is the only one.
+const POLY_HI = 0xc96c5795;
+const POLY_LO = 0xd7870f42;
+const TABLE_HI = new Uint32Array(256);
+const TABLE_LO = new Uint32Array(256);
+for (let n = 0; n < 256; n++) {
+    let lo = n;
+    let hi = 0;
+    for (let k = 0; k < 8; k++) {
+        const carry = lo & 1;
+        lo = ((lo >>> 1) | (hi << 31)) >>> 0;
+        hi >>>= 1;
+        if (carry) {
+            lo = (lo ^ POLY_LO) >>> 0;
+            hi = (hi ^ POLY_HI) >>> 0;
+        }
+    }
+    TABLE_HI[n] = hi;
+    TABLE_LO[n] = lo;
+}
+/** A running CRC-64 as xz computes it. */
+class Crc64 {
+    hi = 0xffffffff;
+    lo = 0xffffffff;
+    update(bytes) {
+        let hi = this.hi;
+        let lo = this.lo;
+        for (const b of bytes) {
+            const i = (lo ^ b) & 0xff;
+            lo = (((lo >>> 8) | (hi << 24)) ^ TABLE_LO[i]) >>> 0;
+            hi = ((hi >>> 8) ^ TABLE_HI[i]) >>> 0;
+        }
+        this.hi = hi;
+        this.lo = lo;
+    }
+    /** The 8 bytes, little-endian, as xz stores them. */
+    digest() {
+        const out = Buffer.alloc(8);
+        out.writeUInt32LE(~this.lo >>> 0, 0);
+        out.writeUInt32LE(~this.hi >>> 0, 4);
+        return out;
+    }
+}
+exports.Crc64 = Crc64;
+/** xz check IDs this package computes. */
+exports.CHECK_NONE = 0x00;
+exports.CHECK_CRC32 = 0x01;
+exports.CHECK_CRC64 = 0x04;
+exports.CHECK_SHA256 = 0x0a;
+/** Size in bytes of each xz check ID, including the ones reserved for future use. */
+const CHECK_SIZES = [0, 4, 4, 4, 8, 8, 8, 16, 16, 16, 32, 32, 32, 64, 64, 64];
+function checkSize(id) {
+    return CHECK_SIZES[id & 0x0f];
+}
+function checkName(id) {
+    return id === exports.CHECK_NONE ? 'none' : id === exports.CHECK_CRC32 ? 'CRC32' : id === exports.CHECK_CRC64 ? 'CRC64' : id === exports.CHECK_SHA256 ? 'SHA-256' : `check ID ${id}`;
+}
+/** A check of a known ID, or undefined for an ID this package cannot compute. */
+function makeCheck(id) {
+    if (id === exports.CHECK_NONE)
+        return { update: () => undefined, digest: () => new Uint8Array(0) };
+    if (id === exports.CHECK_CRC32) {
+        let c = 0;
+        return {
+            update: b => {
+                c = (0, crc32_1.crc32)(b, c);
+            },
+            digest: () => {
+                const out = Buffer.alloc(4);
+                out.writeUInt32LE(c, 0);
+                return out;
+            },
+        };
+    }
+    if (id === exports.CHECK_CRC64)
+        return new Crc64();
+    if (id === exports.CHECK_SHA256) {
+        const h = crypto.createHash('sha256');
+        return { update: b => h.update(b), digest: () => h.digest() };
+    }
+    return undefined;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,364 @@
+#!/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:
+  archive-defuse inspect <file> [options]
+  archive-defuse defuse <in> <out> [options]
+
+Options:
+  --password-file <path>    read passwords from a file, one per line; ARCHIVE_DEFUSE_PASSWORD holds one
+  --plugin <module>         load plugins from a file or an installed package, repeatable
+  --config <module>         load a whole options object, repeatable; the other options apply on top
+  --keep-type <type>        keep entries of this MIME type or file extension unchanged, repeatable
+  --defuse-inner-archives   defuse archives inside the archive, such as the tar inside a .tar.gz
+  --strip-metadata
+  --limit <name>=<value>    fileSize, entries, decompressedBytes, totalDecompressedBytes, compressionRatio,
+                            dictionaryBytes, 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 {
+}
+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 stripMetadata = false;
+    let json = false;
+    let password = process.env.ARCHIVE_DEFUSE_PASSWORD;
+    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':
+                // The empty password is always tried, so a blank line adds nothing.
+                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 ArchiveOptions 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 '--keep-type':
+                ordered.push((0, plugins_1.passThrough)([next()]));
+                break;
+            case '--defuse-inner-archives':
+                ordered.push((0, plugins_1.archivePlugin)());
+                break;
+            case '--strip-metadata':
+                stripMetadata = true;
+                break;
+            case '--limit': {
+                const [name, value] = next().split('=');
+                if (value === undefined)
+                    throw new UsageError('--limit expects name=value');
+                if (name === 'fileSize' || name === 'decompressedBytes' || name === 'totalDecompressedBytes' || name === 'dictionaryBytes')
+                    limits[name] = parseSize(value);
+                else if (name === 'entries' || name === 'compressionRatio' || name === 'nestingDepth' || name === 'timeMs') {
+                    // 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 ARCHIVE_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 (stripMetadata)
+        options.stripMetadata = true;
+    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('.bin');
+        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 archive 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 ?? 'unknown format'}, ${i.entries ?? 0} entries`];
+    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 an entry name from the archive. 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.inspectArchiveSource)(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.disarmArchiveSource)(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 archive 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/codecs.d.ts

@@ -0,0 +1,39 @@
+import * as stream from 'node:stream';
+type ZlibStream = stream.Transform & {
+    bytesWritten: number;
+};
+/**
+ * Node's zstd streams, where the running Node has them. Node 18, Node 20 and early releases of Node 22 do not. The
+ * choice is made once, when the module loads. Without them this package reads and writes no zstd data, and has no
+ * code of its own for it.
+ */
+type ZstdFactory = (options?: {
+    params?: Record<number, number>;
+}) => ZlibStream;
+export declare const zstdDecompressor: ZstdFactory | undefined;
+export declare const zstdCompressor: ZstdFactory | undefined;
+/** How much of its input a transform has used. It grows as the transform works and ends at the total. */
+export interface Consumed {
+    bytes: number;
+}
+/**
+ * Runs `chunks` through a zlib, Brotli or zstd transform and yields what comes out. A corrupt or cut-short stream
+ * throws DataError. `consumed.bytes` follows the input the transform has used, which ends less than it was given when
+ * its stream ends before the input does.
+ */
+export declare function through(transform: ZlibStream, chunks: AsyncIterable<Uint8Array>, consumed?: Consumed): AsyncGenerator<Uint8Array>;
+/** Raw deflate data, decoded. */
+export declare function inflateRaw(chunks: AsyncIterable<Uint8Array>, consumed?: Consumed): AsyncGenerator<Uint8Array>;
+/** Bytes compressed as raw deflate, at zlib's level 6 or `level`. Level 0 writes stored blocks. */
+export declare function deflateRaw(chunks: AsyncIterable<Uint8Array>, level?: number): AsyncGenerator<Uint8Array>;
+/** Brotli data, decoded. */
+export declare function brotliDecode(chunks: AsyncIterable<Uint8Array>, consumed?: Consumed): AsyncGenerator<Uint8Array>;
+/** Bytes compressed as one Brotli stream. */
+export declare function brotliEncode(chunks: AsyncIterable<Uint8Array>): AsyncGenerator<Uint8Array>;
+/** Yields `chunks` while counting them, and calls `each` with the running total before each one. */
+export declare function counted(chunks: AsyncIterable<Uint8Array>, each: (total: number) => void): AsyncGenerator<Uint8Array>;
+/** One chunk as an async iterable. */
+export declare function once(b: Uint8Array): AsyncGenerator<Uint8Array>;
+/** Every chunk, joined. Only for data the caller has already bounded. */
+export declare function collect(chunks: AsyncIterable<Uint8Array>): Promise<Buffer>;
+export {};

package/dist/codecs.js

@@ -0,0 +1,124 @@
+"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.zstdCompressor = exports.zstdDecompressor = void 0;
+exports.through = through;
+exports.inflateRaw = inflateRaw;
+exports.deflateRaw = deflateRaw;
+exports.brotliDecode = brotliDecode;
+exports.brotliEncode = brotliEncode;
+exports.counted = counted;
+exports.once = once;
+exports.collect = collect;
+const stream = __importStar(require("node:stream"));
+const zlib = __importStar(require("node:zlib"));
+const errors_1 = require("./errors");
+const zstd = zlib;
+exports.zstdDecompressor = zstd.createZstdDecompress;
+exports.zstdCompressor = zstd.createZstdCompress;
+/**
+ * True for an error zlib, Brotli or zstd gave for corrupt or cut-short input. Their errors carry a numeric errno, and
+ * an I/O error or a limit thrown on the input side keeps its own code.
+ */
+function isCodecError(e) {
+    const { code, errno } = (e ?? {});
+    if (code === 'ERR_ZLIB_INITIALIZATION_FAILED')
+        return true;
+    return typeof code === 'string' && typeof errno === 'number' && (code.startsWith('Z_') || code.startsWith('ZSTD_') || code.startsWith('ERR_'));
+}
+/**
+ * Runs `chunks` through a zlib, Brotli or zstd transform and yields what comes out. A corrupt or cut-short stream
+ * throws DataError. `consumed.bytes` follows the input the transform has used, which ends less than it was given when
+ * its stream ends before the input does.
+ */
+async function* through(transform, chunks, consumed) {
+    const src = stream.Readable.from(chunks);
+    src.on('error', err => transform.destroy(err));
+    src.pipe(transform);
+    try {
+        for await (const c of transform) {
+            if (consumed)
+                consumed.bytes = transform.bytesWritten;
+            yield c;
+        }
+    }
+    catch (err) {
+        if (isCodecError(err))
+            throw new errors_1.DataError(err.message, /unexpected end/i.test(err.message));
+        throw err;
+    }
+    finally {
+        if (consumed)
+            consumed.bytes = transform.bytesWritten;
+        src.destroy();
+        transform.destroy();
+    }
+}
+/** Raw deflate data, decoded. */
+function inflateRaw(chunks, consumed) {
+    return through(zlib.createInflateRaw(), chunks, consumed);
+}
+/** Bytes compressed as raw deflate, at zlib's level 6 or `level`. Level 0 writes stored blocks. */
+function deflateRaw(chunks, level = 6) {
+    return through(zlib.createDeflateRaw({ level }), chunks);
+}
+/** Brotli data, decoded. */
+function brotliDecode(chunks, consumed) {
+    return through(zlib.createBrotliDecompress(), chunks, consumed);
+}
+/** Bytes compressed as one Brotli stream. */
+function brotliEncode(chunks) {
+    return through(zlib.createBrotliCompress(), chunks);
+}
+/** Yields `chunks` while counting them, and calls `each` with the running total before each one. */
+async function* counted(chunks, each) {
+    let total = 0;
+    for await (const c of chunks) {
+        total += c.length;
+        each(total);
+        yield c;
+    }
+}
+/** One chunk as an async iterable. */
+async function* once(b) {
+    yield b;
+}
+/** Every chunk, joined. Only for data the caller has already bounded. */
+async function collect(chunks) {
+    const parts = [];
+    for await (const c of chunks)
+        parts.push(c);
+    return Buffer.concat(parts);
+}