@patrickdk77/archive-defuse 0.0.0-stage → 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,284 @@
+/** High-level kind of a finding. */
+export declare enum ArchiveCategory {
+    Corrupted = "CORRUPTED",
+    Structure = "STRUCTURE",
+    Name = "NAME",
+    Link = "LINK",
+    Special = "SPECIAL",
+    Permissions = "PERMISSIONS",
+    Encrypted = "ENCRYPTED",
+    Compression = "COMPRESSION",
+    Entry = "ENTRY",
+    Metadata = "METADATA",
+    Limit = "LIMIT",
+    Processing = "PROCESSING"
+}
+/** Exact variant of a finding. */
+export declare enum ArchiveDetail {
+    Unparseable = "UNPARSEABLE",
+    Truncated = "TRUNCATED",
+    DataError = "DATA_ERROR",
+    EntryData = "ENTRY_DATA",
+    CheckFailed = "CHECK_FAILED",
+    LeadingBytes = "LEADING_BYTES",
+    TrailingBytes = "TRAILING_BYTES",
+    HiddenData = "HIDDEN_DATA",
+    Polyglot = "POLYGLOT",
+    SeveralEndRecords = "SEVERAL_END_RECORDS",
+    HeaderMismatch = "HEADER_MISMATCH",
+    OffsetShift = "OFFSET_SHIFT",
+    Overlap = "OVERLAP",
+    ExtraField = "EXTRA_FIELD",
+    NonFileData = "NON_FILE_DATA",
+    MultipleStreams = "MULTIPLE_STREAMS",
+    MalformedHeader = "MALFORMED_HEADER",
+    MultiVolume = "MULTI_VOLUME",
+    StreamPadding = "STREAM_PADDING",
+    BadPadding = "BAD_PADDING",
+    IndexMismatch = "INDEX_MISMATCH",
+    SizeMismatch = "SIZE_MISMATCH",
+    NoCheck = "NO_CHECK",
+    UnknownCheck = "UNKNOWN_CHECK",
+    UnknownProperty = "UNKNOWN_PROPERTY",
+    EmptyStartHeader = "EMPTY_START_HEADER",
+    Traversal = "TRAVERSAL",
+    Absolute = "ABSOLUTE",
+    DriveLetter = "DRIVE_LETTER",
+    Backslash = "BACKSLASH",
+    EmptySegment = "EMPTY_SEGMENT",
+    ControlCharacter = "CONTROL_CHARACTER",
+    WindowsReserved = "WINDOWS_RESERVED",
+    Encoding = "ENCODING",
+    UnicodePath = "UNICODE_PATH",
+    Empty = "EMPTY",
+    TooLong = "TOO_LONG",
+    Duplicate = "DUPLICATE",
+    CaseCollision = "CASE_COLLISION",
+    NormalizationCollision = "NORMALIZATION_COLLISION",
+    FileDirectoryClash = "FILE_DIRECTORY_CLASH",
+    ShortNameCollision = "SHORT_NAME_COLLISION",
+    Symlink = "SYMLINK",
+    Hardlink = "HARDLINK",
+    Outside = "OUTSIDE",
+    Dangling = "DANGLING",
+    ThroughLink = "THROUGH_LINK",
+    Device = "DEVICE",
+    Fifo = "FIFO",
+    Socket = "SOCKET",
+    UnknownType = "UNKNOWN_TYPE",
+    AntiItem = "ANTI_ITEM",
+    Setuid = "SETUID",
+    Setgid = "SETGID",
+    Sticky = "STICKY",
+    Capability = "CAPABILITY",
+    ZipCrypto = "ZIPCRYPTO",
+    Aes128 = "AES_128",
+    Aes192 = "AES_192",
+    Aes256 = "AES_256",
+    Decrypted = "DECRYPTED",
+    EmptyPassword = "EMPTY_PASSWORD",
+    PasswordRequired = "PASSWORD_REQUIRED",
+    Unsupported = "UNSUPPORTED",
+    Header = "HEADER",
+    UnsupportedMethod = "UNSUPPORTED_METHOD",
+    UnsupportedFeature = "UNSUPPORTED_FEATURE",
+    UnusualMethod = "UNUSUAL_METHOD",
+    Unavailable = "UNAVAILABLE",
+    NoPlugin = "NO_PLUGIN",
+    TypeMismatch = "TYPE_MISMATCH",
+    PluginPassed = "PLUGIN_PASSED",
+    PluginScrubbed = "PLUGIN_SCRUBBED",
+    PluginFailed = "PLUGIN_FAILED",
+    PluginRemoved = "PLUGIN_REMOVED",
+    Comment = "COMMENT",
+    Stripped = "STRIPPED",
+    FileSize = "FILE_SIZE",
+    EntryCount = "ENTRY_COUNT",
+    DecompressedSize = "DECOMPRESSED_SIZE",
+    TotalDecompressedSize = "TOTAL_DECOMPRESSED_SIZE",
+    Ratio = "RATIO",
+    DictionarySize = "DICTIONARY_SIZE",
+    NestingDepth = "NESTING_DEPTH",
+    Time = "TIME",
+    MemoryFallback = "MEMORY_FALLBACK",
+    VerificationFailed = "VERIFICATION_FAILED",
+    ContentRemoved = "CONTENT_REMOVED"
+}
+export type ArchiveFindingAction = 'reject' | 'strip' | 'info';
+/**
+ * A finding as any package of the defuse family reports it. Category and detail are plain strings, since the string
+ * enums of two packages never match each other.
+ */
+export interface DefuseFinding {
+    category: string;
+    detail: string;
+    /** Plain sentence, safe to show the uploader. */
+    description: string;
+    /** Default action after any caller override. */
+    action: 'reject' | 'strip' | 'info';
+    /** Where in the file, such as the name of an entry. */
+    location?: string;
+    /** Extra values: the entry name, sizes, counts, the plugin name. */
+    data?: Record<string, string | number>;
+    /**
+     * Set when the finding comes from inside a contained file, such as a PDF inside the archive: the file's name, with
+     * " > " between nesting levels. `location` then starts with where that file sits.
+     */
+    attachment?: string;
+    /** How much the finding adds to a score, set by the package that made it. */
+    weight?: number;
+}
+/** A finding archive-defuse makes itself. */
+export interface ArchiveFinding extends DefuseFinding {
+    category: ArchiveCategory;
+    detail: ArchiveDetail;
+}
+export declare enum ArchiveRisk {
+    None = "NONE",
+    Low = "LOW",
+    Medium = "MEDIUM",
+    High = "HIGH",
+    Critical = "CRITICAL",
+    /** The file could not be inspected: unparseable, an entry no password opens, or a limit stopped the run. */
+    Unknown = "UNKNOWN"
+}
+/** The formats archive-defuse reads and writes. */
+export type ArchiveFormat = 'zip' | 'tar' | 'gzip' | 'bzip2' | 'zstd' | 'brotli' | 'cab' | '7z' | 'xz' | 'lzma';
+export interface ArchiveInspection {
+    status: 'clean' | 'strippable' | 'rejected';
+    /** 0 to 100, null when risk is UNKNOWN. */
+    score: number | null;
+    risk: ArchiveRisk;
+    findings: DefuseFinding[];
+    /** The format the content was read as. Absent when it matched none. */
+    format?: ArchiveFormat;
+    /** Entries in the archive, or 1 for a compressed file. Absent when the archive could not be opened. */
+    entries?: number;
+}
+export interface ArchiveDisarmResult {
+    status: 'clean' | 'defused' | 'rejected';
+    /** The uploaded file and its score. */
+    before: ArchiveInspection;
+    /** The output and its remaining score. Absent when rejected. */
+    after?: ArchiveInspection;
+    /** Findings whose content was removed. */
+    removed: DefuseFinding[];
+}
+/** Random-access input. A buffer, a local file and an S3 ranged GetObject all fit. */
+export interface ByteSource {
+    size(): Promise<number>;
+    read(offset: number, length: number): Promise<Uint8Array>;
+    close?(): Promise<void>;
+}
+/** Append-only output. Never seeks. */
+export interface ByteSink {
+    write(chunk: Uint8Array): Promise<void>;
+    close(): Promise<void>;
+    /** Called instead of close() when copying to the sink fails, so a partial output is not taken for a whole one. */
+    abort?(error: unknown): Promise<void>;
+}
+export interface ArchiveLimits {
+    /** Bytes in the upload. Not enforced unless set. */
+    fileSize?: number;
+    /** Entries in the archive. Default 10,000. */
+    entries?: number;
+    /** Decompressed size of any one entry, declared or actual, in bytes. Default 512 MiB. */
+    decompressedBytes?: number;
+    /** Decompressed sizes of the entries read in one run added together, declared or actual, in bytes. Default 2 GiB. */
+    totalDecompressedBytes?: number;
+    /**
+     * Decompressed bytes per compressed byte of one entry, checked once the entry passes 1 MiB decompressed. Default
+     * 1,000.
+     */
+    compressionRatio?: number;
+    /**
+     * The deepest an archive may sit in the upload. The upload is at depth 0 and a file inside it at 1, and files of
+     * every format in between count. Default 10, since an archive can hold itself.
+     */
+    nestingDepth?: number;
+    /**
+     * The dictionary memory LZMA decoding may need, in bytes: one LZMA or LZMA2 stream's dictionary, or those of all the
+     * coders of one 7z folder together with their probability tables. A dictionary larger than the declared decoded size
+     * counts at that size. Default 256 MiB.
+     */
+    dictionaryBytes?: number;
+    /** Milliseconds for the whole run. Not enforced unless set. */
+    timeMs?: number;
+}
+/** What a contained file plugin learns of the run, with nothing format-specific, so any package of the family can make one. */
+export interface PluginContext {
+    /** The depth of the file itself: 0 for the upload, 1 for a file inside it, and so on, whatever the formats. */
+    depth: number;
+    /** When a time limit is set, the Date.now() value the whole run must finish by. Nested runs share it. */
+    deadline?: number;
+}
+export interface ContainedFile {
+    name?: string;
+    /** The MIME type the container declares for the file. Archives declare none. */
+    declaredType?: string;
+    /** From the first bytes. */
+    sniffedType?: string;
+    /** Decoded size. */
+    size: number;
+    location: string;
+    /** The depth of the file itself: 0 for the upload, 1 for a file inside it, and so on, whatever the formats. */
+    depth: number;
+    /** Decoded and decrypted bytes. */
+    source: ByteSource;
+}
+/** What a file plugin did, plus anything it found inside the file. */
+export interface ContainedFileResult {
+    result: 'scrubbed' | 'passed' | 'removed';
+    /** Findings inside the file as it arrived. They go into the report of the file that contains it. */
+    findings?: DefuseFinding[];
+    /** Findings inside the bytes the plugin kept. They go into the report of the output. */
+    outputFindings?: DefuseFinding[];
+}
+export interface ContainedFilePlugin {
+    kind: 'file';
+    name: string;
+    accepts(file: ContainedFile): boolean | Promise<boolean>;
+    /** Writes the bytes to keep. Returning 'removed' drops the file after all. */
+    process(file: ContainedFile, sink: ByteSink, context: PluginContext): Promise<'scrubbed' | 'passed' | 'removed' | ContainedFileResult>;
+}
+export interface ArchiveActionOverride {
+    category: ArchiveCategory;
+    detail?: ArchiveDetail;
+    action: ArchiveFindingAction;
+}
+export interface ArchiveScoreWeight {
+    category: ArchiveCategory;
+    detail?: ArchiveDetail;
+    weight: number;
+}
+/** Lower bound of each band. */
+export interface ArchiveScoreBands {
+    low: number;
+    medium: number;
+    high: number;
+    critical: number;
+}
+export interface ArchiveOptions {
+    /**
+     * Passwords for encrypted entries. Each is tried in order on each encrypted entry, and the empty password after
+     * them.
+     */
+    password?: string | string[];
+    /** Limits left out take the defaults listed on ArchiveLimits. */
+    limits?: ArchiveLimits;
+    /** Default false. The rewrite drops comments, owner names and ids, timestamps and extended attributes. */
+    stripMetadata?: boolean;
+    actionOverrides?: ArchiveActionOverride[];
+    scoreWeights?: ArchiveScoreWeight[];
+    scoreBands?: ArchiveScoreBands;
+    /** Every file entry goes to these in order. The first that accepts it decides. */
+    filePlugins?: ContainedFilePlugin[];
+    /** Directory for temporary files. Defaults to os.tmpdir(). */
+    tempDir?: string;
+    /**
+     * Default 8 MiB. disarmArchiveSource keeps its copy of the upload in memory up to this size and in a temporary file
+     * above it. Each entry handed to the plugins above it goes through a temporary file, and the copies plugins keep
+     * share this much memory.
+     */
+    memoryThreshold?: number;
+}

package/dist/types.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArchiveRisk = exports.ArchiveDetail = exports.ArchiveCategory = void 0;
+/** High-level kind of a finding. */
+var ArchiveCategory;
+(function (ArchiveCategory) {
+    ArchiveCategory["Corrupted"] = "CORRUPTED";
+    ArchiveCategory["Structure"] = "STRUCTURE";
+    ArchiveCategory["Name"] = "NAME";
+    ArchiveCategory["Link"] = "LINK";
+    ArchiveCategory["Special"] = "SPECIAL";
+    ArchiveCategory["Permissions"] = "PERMISSIONS";
+    ArchiveCategory["Encrypted"] = "ENCRYPTED";
+    ArchiveCategory["Compression"] = "COMPRESSION";
+    ArchiveCategory["Entry"] = "ENTRY";
+    ArchiveCategory["Metadata"] = "METADATA";
+    ArchiveCategory["Limit"] = "LIMIT";
+    ArchiveCategory["Processing"] = "PROCESSING";
+})(ArchiveCategory || (exports.ArchiveCategory = ArchiveCategory = {}));
+/** Exact variant of a finding. */
+var ArchiveDetail;
+(function (ArchiveDetail) {
+    // CORRUPTED
+    ArchiveDetail["Unparseable"] = "UNPARSEABLE";
+    ArchiveDetail["Truncated"] = "TRUNCATED";
+    ArchiveDetail["DataError"] = "DATA_ERROR";
+    ArchiveDetail["EntryData"] = "ENTRY_DATA";
+    ArchiveDetail["CheckFailed"] = "CHECK_FAILED";
+    // STRUCTURE
+    ArchiveDetail["LeadingBytes"] = "LEADING_BYTES";
+    ArchiveDetail["TrailingBytes"] = "TRAILING_BYTES";
+    ArchiveDetail["HiddenData"] = "HIDDEN_DATA";
+    ArchiveDetail["Polyglot"] = "POLYGLOT";
+    ArchiveDetail["SeveralEndRecords"] = "SEVERAL_END_RECORDS";
+    ArchiveDetail["HeaderMismatch"] = "HEADER_MISMATCH";
+    ArchiveDetail["OffsetShift"] = "OFFSET_SHIFT";
+    ArchiveDetail["Overlap"] = "OVERLAP";
+    ArchiveDetail["ExtraField"] = "EXTRA_FIELD";
+    ArchiveDetail["NonFileData"] = "NON_FILE_DATA";
+    ArchiveDetail["MultipleStreams"] = "MULTIPLE_STREAMS";
+    ArchiveDetail["MalformedHeader"] = "MALFORMED_HEADER";
+    ArchiveDetail["MultiVolume"] = "MULTI_VOLUME";
+    ArchiveDetail["StreamPadding"] = "STREAM_PADDING";
+    ArchiveDetail["BadPadding"] = "BAD_PADDING";
+    ArchiveDetail["IndexMismatch"] = "INDEX_MISMATCH";
+    ArchiveDetail["SizeMismatch"] = "SIZE_MISMATCH";
+    ArchiveDetail["NoCheck"] = "NO_CHECK";
+    ArchiveDetail["UnknownCheck"] = "UNKNOWN_CHECK";
+    ArchiveDetail["UnknownProperty"] = "UNKNOWN_PROPERTY";
+    ArchiveDetail["EmptyStartHeader"] = "EMPTY_START_HEADER";
+    // NAME
+    ArchiveDetail["Traversal"] = "TRAVERSAL";
+    ArchiveDetail["Absolute"] = "ABSOLUTE";
+    ArchiveDetail["DriveLetter"] = "DRIVE_LETTER";
+    ArchiveDetail["Backslash"] = "BACKSLASH";
+    ArchiveDetail["EmptySegment"] = "EMPTY_SEGMENT";
+    ArchiveDetail["ControlCharacter"] = "CONTROL_CHARACTER";
+    ArchiveDetail["WindowsReserved"] = "WINDOWS_RESERVED";
+    ArchiveDetail["Encoding"] = "ENCODING";
+    ArchiveDetail["UnicodePath"] = "UNICODE_PATH";
+    ArchiveDetail["Empty"] = "EMPTY";
+    ArchiveDetail["TooLong"] = "TOO_LONG";
+    ArchiveDetail["Duplicate"] = "DUPLICATE";
+    ArchiveDetail["CaseCollision"] = "CASE_COLLISION";
+    ArchiveDetail["NormalizationCollision"] = "NORMALIZATION_COLLISION";
+    ArchiveDetail["FileDirectoryClash"] = "FILE_DIRECTORY_CLASH";
+    ArchiveDetail["ShortNameCollision"] = "SHORT_NAME_COLLISION";
+    // LINK
+    ArchiveDetail["Symlink"] = "SYMLINK";
+    ArchiveDetail["Hardlink"] = "HARDLINK";
+    ArchiveDetail["Outside"] = "OUTSIDE";
+    ArchiveDetail["Dangling"] = "DANGLING";
+    ArchiveDetail["ThroughLink"] = "THROUGH_LINK";
+    // SPECIAL
+    ArchiveDetail["Device"] = "DEVICE";
+    ArchiveDetail["Fifo"] = "FIFO";
+    ArchiveDetail["Socket"] = "SOCKET";
+    ArchiveDetail["UnknownType"] = "UNKNOWN_TYPE";
+    ArchiveDetail["AntiItem"] = "ANTI_ITEM";
+    // PERMISSIONS
+    ArchiveDetail["Setuid"] = "SETUID";
+    ArchiveDetail["Setgid"] = "SETGID";
+    ArchiveDetail["Sticky"] = "STICKY";
+    ArchiveDetail["Capability"] = "CAPABILITY";
+    // ENCRYPTED
+    ArchiveDetail["ZipCrypto"] = "ZIPCRYPTO";
+    ArchiveDetail["Aes128"] = "AES_128";
+    ArchiveDetail["Aes192"] = "AES_192";
+    ArchiveDetail["Aes256"] = "AES_256";
+    ArchiveDetail["Decrypted"] = "DECRYPTED";
+    ArchiveDetail["EmptyPassword"] = "EMPTY_PASSWORD";
+    ArchiveDetail["PasswordRequired"] = "PASSWORD_REQUIRED";
+    ArchiveDetail["Unsupported"] = "UNSUPPORTED";
+    ArchiveDetail["Header"] = "HEADER";
+    // COMPRESSION
+    ArchiveDetail["UnsupportedMethod"] = "UNSUPPORTED_METHOD";
+    ArchiveDetail["UnsupportedFeature"] = "UNSUPPORTED_FEATURE";
+    ArchiveDetail["UnusualMethod"] = "UNUSUAL_METHOD";
+    ArchiveDetail["Unavailable"] = "UNAVAILABLE";
+    // ENTRY
+    ArchiveDetail["NoPlugin"] = "NO_PLUGIN";
+    ArchiveDetail["TypeMismatch"] = "TYPE_MISMATCH";
+    ArchiveDetail["PluginPassed"] = "PLUGIN_PASSED";
+    ArchiveDetail["PluginScrubbed"] = "PLUGIN_SCRUBBED";
+    ArchiveDetail["PluginFailed"] = "PLUGIN_FAILED";
+    ArchiveDetail["PluginRemoved"] = "PLUGIN_REMOVED";
+    // METADATA
+    ArchiveDetail["Comment"] = "COMMENT";
+    ArchiveDetail["Stripped"] = "STRIPPED";
+    // LIMIT
+    ArchiveDetail["FileSize"] = "FILE_SIZE";
+    ArchiveDetail["EntryCount"] = "ENTRY_COUNT";
+    ArchiveDetail["DecompressedSize"] = "DECOMPRESSED_SIZE";
+    ArchiveDetail["TotalDecompressedSize"] = "TOTAL_DECOMPRESSED_SIZE";
+    ArchiveDetail["Ratio"] = "RATIO";
+    ArchiveDetail["DictionarySize"] = "DICTIONARY_SIZE";
+    ArchiveDetail["NestingDepth"] = "NESTING_DEPTH";
+    ArchiveDetail["Time"] = "TIME";
+    // PROCESSING
+    ArchiveDetail["MemoryFallback"] = "MEMORY_FALLBACK";
+    ArchiveDetail["VerificationFailed"] = "VERIFICATION_FAILED";
+    ArchiveDetail["ContentRemoved"] = "CONTENT_REMOVED";
+})(ArchiveDetail || (exports.ArchiveDetail = ArchiveDetail = {}));
+var ArchiveRisk;
+(function (ArchiveRisk) {
+    ArchiveRisk["None"] = "NONE";
+    ArchiveRisk["Low"] = "LOW";
+    ArchiveRisk["Medium"] = "MEDIUM";
+    ArchiveRisk["High"] = "HIGH";
+    ArchiveRisk["Critical"] = "CRITICAL";
+    /** The file could not be inspected: unparseable, an entry no password opens, or a limit stopped the run. */
+    ArchiveRisk["Unknown"] = "UNKNOWN";
+})(ArchiveRisk || (exports.ArchiveRisk = ArchiveRisk = {}));

package/dist/unpack.d.ts

@@ -0,0 +1,67 @@
+import type { EntryKind } from './model';
+import type { ArchiveFormat, ArchiveLimits, ByteSource } from './types';
+/** One entry of an archive, as `openArchive` lists it. */
+export interface ArchiveReaderEntry {
+    /** Position in the archive's own order. */
+    index: number;
+    /**
+     * The name as the archive gives it, decoded, with no rule applied: it can climb out with "..", be absolute or repeat
+     * another entry's name. Folders end in "/". The one entry of a compressed file has the name the file stores, or "".
+     */
+    name: string;
+    kind: EntryKind;
+    /** Decoded size the headers declare, or undefined for a compressed file, whose size is known only once read. */
+    size?: number;
+    /** Permission bits, when the format records them. */
+    mode?: number;
+    /** A link's target, when the entry is a link. */
+    linkTarget?: string;
+    /** True when the entry is encrypted. */
+    encrypted: boolean;
+}
+export interface OpenArchiveOptions {
+    /** Folder for temporary files, which an XZ entry of a ZIP archive needs. Defaults to `os.tmpdir()`. */
+    tempDir?: string;
+    /** Bytes an XZ entry of a ZIP archive holds in memory before a temporary file takes over. Default 8 MiB. */
+    memoryThreshold?: number;
+    /** One password or a list, tried in order on each encrypted entry, then the empty password. */
+    password?: string | string[];
+    /** The limits of `inspectArchive`, with its defaults: every read counts toward them, and the total is shared. */
+    limits?: ArchiveLimits;
+}
+/** An archive opened for reading. */
+export interface ArchiveReader {
+    format: ArchiveFormat;
+    entries: ArchiveReaderEntry[];
+    /** The first entry with this exact name, or undefined. */
+    find(name: string): ArchiveReaderEntry | undefined;
+    /** An entry's content, decrypted and decoded, checked against its size and CRC as it goes. */
+    stream(entry: ArchiveReaderEntry | string): AsyncIterable<Uint8Array>;
+    /** An entry's whole content. */
+    bytes(entry: ArchiveReaderEntry | string): Promise<Buffer>;
+    /** An entry's whole content as text, UTF-8 unless `encoding` says otherwise. */
+    text(entry: ArchiveReaderEntry | string, encoding?: BufferEncoding): Promise<string>;
+    /** Closes the source. */
+    close(): Promise<void>;
+}
+/**
+ * Thrown when an archive cannot be read: not a format this package reads, a limit, a missing password, or data that
+ * does not decode. `category` and `detail` name the finding `inspectArchive` would report.
+ */
+export declare class ArchiveReadError extends Error {
+    readonly category: string;
+    readonly detail: string;
+    readonly data?: Record<string, string | number> | undefined;
+    constructor(message: string, category: string, detail: string, data?: Record<string, string | number> | undefined);
+}
+/**
+ * Opens an archive or a compressed file for reading. The format comes from the content, as for `inspectArchive`. The
+ * entries are listed at once; content is read only when asked for. The source is closed by `close()`, or at once when
+ * opening fails.
+ */
+export declare function openArchive(input: Uint8Array | ByteSource, options?: OpenArchiveOptions): Promise<ArchiveReader>;
+/**
+ * Decodes a compressed file, such as gzip, bzip2, zstd, Brotli, xz or .lzma, to its content. An archive of several
+ * entries throws; `openArchive` reads those.
+ */
+export declare function decompress(input: Uint8Array | ByteSource, options?: OpenArchiveOptions): Promise<Buffer>;

package/dist/unpack.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArchiveReadError = void 0;
+exports.openArchive = openArchive;
+exports.decompress = decompress;
+// Reading archives and compressed files as a library: list the entries of any format this package reads and read
+// their content, under the same limits the inspection uses. Nothing here applies the rules or writes files; the names
+// are as the archive gives them.
+const engine_1 = require("./engine");
+const errors_1 = require("./errors");
+const formats_1 = require("./formats");
+const io_1 = require("./io");
+/**
+ * Thrown when an archive cannot be read: not a format this package reads, a limit, a missing password, or data that
+ * does not decode. `category` and `detail` name the finding `inspectArchive` would report.
+ */
+class ArchiveReadError extends Error {
+    category;
+    detail;
+    data;
+    constructor(message, category, detail, data) {
+        super(message);
+        this.category = category;
+        this.detail = detail;
+        this.data = data;
+    }
+}
+exports.ArchiveReadError = ArchiveReadError;
+/** The error a reader throws for what stopped it. Time and nesting limits and I/O errors pass as they are. */
+function readError(e) {
+    if ((0, errors_1.stopsTree)(e) || e instanceof ArchiveReadError)
+        return e;
+    if (e instanceof errors_1.StopError)
+        return new ArchiveReadError(e.message, e.category, e.detail, e.data);
+    if (e instanceof errors_1.CheckError)
+        return new ArchiveReadError(e.message, 'CORRUPTED', 'CHECK_FAILED', { check: e.check });
+    if (e instanceof errors_1.DataError)
+        return new ArchiveReadError(e.message, 'CORRUPTED', e.truncated ? 'TRUNCATED' : 'DATA_ERROR');
+    if (e instanceof errors_1.UnsupportedError)
+        return new ArchiveReadError(e.message, 'COMPRESSION', e.method ? 'UNSUPPORTED_METHOD' : 'UNSUPPORTED_FEATURE');
+    return e;
+}
+const hasContent = (e) => e.kind === 'file' || e.kind === 'other';
+/**
+ * Opens an archive or a compressed file for reading. The format comes from the content, as for `inspectArchive`. The
+ * entries are listed at once; content is read only when asked for. The source is closed by `close()`, or at once when
+ * opening fails.
+ */
+async function openArchive(input, options = {}) {
+    const source = input instanceof Uint8Array ? (0, io_1.bufferSource)(input) : input;
+    const limits = (0, engine_1.limitsOf)({ limits: options.limits });
+    const deadline = options.limits?.timeMs !== undefined ? Date.now() + options.limits.timeMs : undefined;
+    const passwords = (0, engine_1.passwordsOf)({ password: options.password });
+    const totals = { decoded: 0 };
+    const temp = new io_1.TempDir(options.tempDir);
+    let archive;
+    try {
+        const size = await source.size();
+        if (limits.fileSize !== undefined && size > limits.fileSize)
+            throw new ArchiveReadError('The file exceeds the file size limit', 'LIMIT', 'FILE_SIZE', { size });
+        archive = await (0, formats_1.openArchive)(source, limits, deadline, passwords, { dir: temp, threshold: options.memoryThreshold ?? 8 * 1024 * 1024 });
+        // ZIP and 7z keep a symbolic link's target as its content.
+        if (archive.linkTarget) {
+            for (const e of archive.entries) {
+                if (e.kind !== 'symlink' || e.broken || e.linkTarget !== undefined)
+                    continue;
+                try {
+                    e.linkTarget = await archive.linkTarget(e, (0, engine_1.makeMeter)(e, limits, deadline, totals));
+                }
+                catch (err) {
+                    if (!(err instanceof errors_1.DataError))
+                        throw err;
+                }
+            }
+        }
+    }
+    catch (e) {
+        await source.close?.();
+        await temp.cleanup();
+        throw readError(e);
+    }
+    const opened = archive;
+    const listed = opened.entries.map(e => ({
+        index: e.index,
+        name: e.name,
+        kind: e.kind,
+        size: opened.single ? undefined : e.size,
+        mode: e.mode,
+        linkTarget: e.linkTarget,
+        encrypted: e.encryption !== undefined,
+    }));
+    const entryOf = (which) => {
+        const listedEntry = typeof which === 'string' ? listed.find(l => l.name === which) : which;
+        const e = listedEntry === undefined ? undefined : opened.entries[listedEntry.index];
+        if (!e)
+            throw new ArchiveReadError(`No entry ${JSON.stringify(typeof which === 'string' ? which : which.name)}`, 'ENTRY', 'NOT_FOUND');
+        if (!hasContent(e))
+            throw new ArchiveReadError(`Entry ${JSON.stringify(e.name)} is a ${e.kind}, which has no content`, 'ENTRY', 'NO_CONTENT');
+        return e;
+    };
+    /** The passwords that open an encrypted entry, in the order to try them; undefined alone for a plain one. */
+    async function* keys(e) {
+        if (!e.encryption) {
+            yield undefined;
+            return;
+        }
+        if (e.encryption.kind === 'unsupported')
+            throw new ArchiveReadError(`Entry ${JSON.stringify(e.name)} uses ${e.encryption.reason}`, 'ENCRYPTED', 'UNSUPPORTED');
+        let any = false;
+        for (const p of passwords) {
+            if (await opened.unlock(e, p)) {
+                any = true;
+                yield p;
+            }
+        }
+        if (!any)
+            throw new ArchiveReadError(`No password opens entry ${JSON.stringify(e.name)}`, 'ENCRYPTED', 'PASSWORD_REQUIRED');
+    }
+    async function* stream(which) {
+        const e = entryOf(which);
+        if (e.broken)
+            throw new ArchiveReadError(`Entry ${JSON.stringify(e.name)} cannot be read: ${e.broken}`, 'CORRUPTED', 'ENTRY_DATA');
+        try {
+            // A stream cannot take back what it gave, so it reads with the first password that opens the entry.
+            for await (const password of keys(e)) {
+                yield* opened.read(e, (0, engine_1.makeMeter)(e, limits, deadline, totals), password);
+                return;
+            }
+        }
+        catch (err) {
+            throw readError(err);
+        }
+    }
+    async function bytes(which) {
+        const e = entryOf(which);
+        if (e.broken)
+            throw new ArchiveReadError(`Entry ${JSON.stringify(e.name)} cannot be read: ${e.broken}`, 'CORRUPTED', 'ENTRY_DATA');
+        let failure;
+        try {
+            // A ZipCrypto header can pass for a wrong password, so a password whose data fails gives way to the next.
+            for await (const password of keys(e)) {
+                const meter = (0, engine_1.makeMeter)(e, limits, deadline, totals);
+                const parts = [];
+                try {
+                    for await (const c of opened.read(e, meter, password))
+                        parts.push(c);
+                    return Buffer.concat(parts);
+                }
+                catch (err) {
+                    totals.decoded -= meter.total;
+                    if (!(err instanceof errors_1.DataError) || e.encryption === undefined)
+                        throw err;
+                    failure = err;
+                }
+            }
+        }
+        catch (err) {
+            throw readError(err);
+        }
+        throw readError(failure);
+    }
+    return {
+        format: opened.format,
+        entries: listed,
+        find: name => listed.find(l => l.name === name),
+        stream,
+        bytes,
+        text: async (which, encoding = 'utf8') => (await bytes(which)).toString(encoding),
+        close: async () => {
+            try {
+                await source.close?.();
+            }
+            finally {
+                await temp.cleanup();
+            }
+        },
+    };
+}
+/**
+ * Decodes a compressed file, such as gzip, bzip2, zstd, Brotli, xz or .lzma, to its content. An archive of several
+ * entries throws; `openArchive` reads those.
+ */
+async function decompress(input, options = {}) {
+    const reader = await openArchive(input, options);
+    try {
+        const formats = ['gzip', 'bzip2', 'zstd', 'brotli', 'xz', 'lzma'];
+        if (!formats.includes(reader.format))
+            throw new ArchiveReadError(`A ${reader.format} archive holds entries; openArchive reads them`, 'FORMAT', 'NOT_SINGLE');
+        return await reader.bytes(reader.entries[0]);
+    }
+    finally {
+        await reader.close();
+    }
+}