@patrickdk77/archive-defuse 0.0.0-stage → 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,311 @@
+/** 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;
+}
+/**
+ * A file's format as a package of the family finds it, among the formats that package reads. The family's router asks
+ * each package and routes the file by the answers.
+ */
+export interface FormatDetection {
+    /** The format's MIME type, such as application/zip. */
+    mimeType: string;
+    /** The format's usual extension, lowercase and without the dot. */
+    extension: string;
+    /** Where the format starts in the file: 0, or the offset of its data when other data comes first. */
+    offset: number;
+    /** Set when the match rests on more than the content, and says what it rests on. */
+    heuristic?: string;
+}
+/** What a detect function may know of a file besides its content. */
+export interface DetectOptions {
+    /** The file's name, as the upload or the container that holds it gives it. */
+    name?: string;
+    /** The MIME type the upload or the container declares. */
+    declaredType?: string;
+    /** The Date.now() value detection must finish by, as `PluginContext.deadline`. */
+    deadline?: number;
+    /** Folder for temporary files. Defaults to `os.tmpdir()`. */
+    tempDir?: string;
+    /** Bytes held in memory before a temporary file takes over. */
+    memoryThreshold?: 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>;