@gyng/remote-zip 0.2.5 → 1.0.0

package/lib/types/crypto.d.ts

@@ -0,0 +1,39 @@
+/** Incremental CRC-32, for verifying decompressed output (including streaming). */
+export declare class Crc32 {
+    private state;
+    update(bytes: Uint8Array): void;
+    digest(): number;
+}
+/** Compute the CRC-32 of `bytes` (the ZIP/IEEE variant). */
+export declare const crc32: (bytes: Uint8Array) => number;
+/** Test seam: raw AES block encryption (FIPS-197), used to validate the core. */
+export declare const aesEncryptBlockRaw: (key: Uint8Array, block: Uint8Array) => Uint8Array;
+/**
+ * Decrypt traditional-ZipCrypto bytes (the 12-byte encryption header is consumed
+ * and stripped). Returns the compressed plaintext and the header's check byte.
+ */
+export declare const decryptZipCrypto: (data: Uint8Array, password: Uint8Array) => {
+    plaintext: Uint8Array;
+    checkByte: number;
+};
+/** Encrypt for ZipCrypto (used by tests to build fixtures). */
+export declare const encryptZipCrypto: (plaintext: Uint8Array, password: Uint8Array, header: Uint8Array) => Uint8Array;
+/** Parse the WinZip AES extra field (id 0x9901): strength + actual method. */
+export declare const parseAesExtra: (extra: ArrayBuffer) => {
+    strength: number;
+    actualMethod: number;
+} | null;
+/** Reasons a WinZip AES decryption can fail (mapped to RemoteZipError codes). */
+export type AesDecryptError = "WRONG_PASSWORD" | "BAD_MAC" | "UNSUPPORTED";
+export declare class CryptoError extends Error {
+    reason: AesDecryptError;
+    constructor(reason: AesDecryptError);
+}
+/**
+ * Decrypt a WinZip AES entry payload (salt || pwVerify || ciphertext || mac).
+ * Verifies the password-check bytes and the authentication code, then returns
+ * the still-compressed plaintext.
+ */
+export declare const decryptWinzipAes: (data: Uint8Array, password: Uint8Array, strength: number) => Promise<Uint8Array>;
+/** Encrypt a WinZip AES payload (used by tests to build fixtures). */
+export declare const encryptWinzipAes: (plaintext: Uint8Array, password: Uint8Array, strength: number, salt: Uint8Array) => Promise<Uint8Array>;

package/lib/types/index.d.mts

@@ -0,0 +1 @@
+export * from "./zip.mjs";

package/lib/types/zip.d.mts

@@ -0,0 +1,453 @@
+export { crc32 } from "./crypto";
+/** Machine-readable discriminant for {@link RemoteZipError}. */
+export type RemoteZipErrorCode = "UNKNOWN" | "CONTENT_LENGTH_MISSING" | "HTTP_ERROR" | "EOCD_NOT_FOUND" | "UNSUPPORTED_ZIP64" | "UNSUPPORTED_ENCRYPTION" | "FILE_NOT_FOUND" | "LOCAL_HEADER_PARSE_FAILED" | "CENTRAL_DIRECTORY_OUT_OF_BOUNDS" | "DECOMPRESSION_LIMIT_EXCEEDED" | "CRC_MISMATCH" | "WRONG_PASSWORD" | "DECRYPTION_FAILED";
+export declare class RemoteZipError extends Error {
+    /** Machine-readable error code, for programmatic handling without matching on `message`. */
+    code: RemoteZipErrorCode;
+    constructor(message: string, code?: RemoteZipErrorCode);
+}
+/** Per-call options for {@link RemoteZip.fetch} / {@link RemoteZip.fetchStream}. */
+export interface EntryDecodeOptions {
+    /** If set, decompression aborts and throws once output would exceed this many bytes. */
+    maxUncompressedSize?: number;
+    /** Aborts this request (in addition to any instance-level signal). */
+    signal?: AbortSignal;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** If set, verify the decompressed output against the entry's CRC-32. */
+    verifyCrc?: boolean;
+    /** Password for an encrypted entry (traditional ZipCrypto or WinZip AES). */
+    password?: string;
+}
+export interface EndOfCentralDirectory {
+    meta: Record<string, unknown>;
+    data: {
+        /** End of central directory signature = 0x06054b50 */
+        signature: ArrayBuffer;
+        /** Number of this disk (or 0xffff for ZIP64) */
+        diskNumber: number;
+        /** Disk where central directory starts (or 0xffff for ZIP64) */
+        cdDisk: number;
+        /** Number of central directory records on this disk (or 0xffff for ZIP64) */
+        centralDirectoryDiskNumber: number;
+        /** Number of central directory records on this disk (or 0xffff for ZIP64) */
+        centralDirectoryRecordCount: number;
+        /** Size of central directory (bytes) (or 0xffffffff for ZIP64) */
+        centralDirectoryByteSize: number;
+        /** Offset of start of central directory, relative to start of archive (or 0xffffffff for ZIP64) */
+        centralDirectoryByteOffset: number;
+        /** Comment */
+        comment: string;
+        /** Comment length (n) */
+        commentLength: number;
+    };
+}
+export interface CentralDirectoryRecord {
+    meta: {
+        /** Length of the entire record */
+        length: number;
+    };
+    data: {
+        /** Central directory file header signature = 0x02014b50 */
+        signature: ArrayBuffer;
+        /** Version of the program this ZIP was made by.
+         *
+         * Upper byte:
+         * - 0 - MS-DOS and OS/2 (FAT / VFAT / FAT32 file systems)
+         * - 1 - Amiga
+         * - 2 - OpenVMS
+         * - 3 - UNIX
+         * - 4 - VM/CMS
+         * - 5 - Atari ST
+         * - 6 - OS/2 H.P.F.S.
+         * - 7 - Macintosh
+         * - 8 - Z-System
+         * - 9 - CP/M
+         * - 10 - Windows NTFS
+         * - 11 - MVS (OS/390 - Z/OS)
+         * - 12 - VSE
+         * - 13 - Acorn Risc
+         * - 14 - VFAT
+         * - 15 - alternate MVS
+         * - 16 - BeOS
+         * - 17 - Tandem
+         * - 18 - OS/400
+         * - 19 - OS/X (Darwin)
+         * - 20 - 255: Unused
+         */
+        versionMadeBy: number;
+        /** Version needed to extract (minimum) */
+        versionToExtract: number;
+        /** General purpose bit flag
+         *
+         * - Bit 00: encrypted file
+         * - Bit 01: compression option
+         * - Bit 02: compression option
+         * - Bit 03: data descriptor
+         * - Bit 04: enhanced deflation
+         * - Bit 05: compressed patched data
+         * - Bit 06: strong encryption
+         * - Bit 07-10: unused
+         * - Bit 11: language encoding
+         * - Bit 12: reserved
+         * - Bit 13: mask header values
+         * - Bit 14-15: reserved
+         */
+        generalPurposeBitFlag: number;
+        /** Compression method; e.g. none = 0, DEFLATE = 8 (or "\0x08\0x00")
+         *
+         * - 00: no compression
+         * - 01: shrunk
+         * - 02: reduced with compression factor 1
+         * - 03: reduced with compression factor 2
+         * - 04: reduced with compression factor 3
+         * - 05: reduced with compression factor 4
+         * - 06: imploded
+         * - 07: reserved
+         * - 08: deflated
+         * - 09: enhanced deflated
+         * - 10: PKWare DCL imploded
+         * - 11: reserved
+         * - 12: compressed using BZIP2
+         * - 13: reserved
+         * - 14: LZMA
+         * - 15-17: reserved
+         * - 18: compressed using IBM TERSE
+         * - 19: IBM LZ77 z
+         * - 98: PPMd version I, Rev 1
+         */
+        compressionMethod: number;
+        /** File last modification time (DOS) */
+        lastModifiedTime: number;
+        /** File last modification date (DOS) */
+        lastModifiedDate: number;
+        /** CRC-32 of uncompressed data
+         * Value computed over file data by CRC-32 algorithm with
+         * 'magic number' 0xdebb20e3 (little endian)
+         */
+        crc32: number;
+        /** Compressed size (or 0xffffffff for ZIP64) */
+        compressedSize: number;
+        /** Uncompressed size (or 0xffffffff for ZIP64) */
+        uncompressedSize: number;
+        /** File name length (n) */
+        filenameLength: number;
+        /** Extra field length (m) */
+        extraFieldLength: number;
+        /** File comment length (k) */
+        fileCommentLength: number;
+        /** Disk number where file starts */
+        startingDiskNumber: number;
+        /** Internal file attributes
+         *
+         * Bit 0: apparent ASCII/text file
+         * Bit 1: reserved
+         * Bit 2: control field records precede logical records
+         * Bits 3-16: unused
+         */
+        internalFileAttributes: number;
+        /** External file attributes (host-system dependent) */
+        externalFileAttributes: number;
+        /** Relative offset of local file header.
+         * This is the number of bytes between the start of the first
+         * disk on which the file occurs, and the start of the local file
+         * header. This allows software reading the central directory to
+         * locate the position of the file inside the ZIP file. */
+        localFileHeaderRelativeOffset: number;
+        /** File name */
+        filename: string;
+        /** Extra field
+         *
+         * Used to store additional information. The field consistes of a sequence of
+         * header and data pairs, where the header has a 2 byte identifier and a 2 byte data size field.
+         */
+        extraField: ArrayBuffer;
+        /** File comment */
+        fileComment: string;
+    };
+}
+export interface LocalFileHeader {
+    meta: {
+        compressedData: ArrayBuffer;
+        /** If the bit at offset 3 (0x08) of the general-purpose flags field is set,
+         * then the CRC-32 and file sizes are not known when the header is written.
+         * The fields in the local header are filled with zero, and the CRC-32 and size are
+         * appended in a 12-byte structure (optionally preceded by a 4-byte signature) immediately
+         * after the compressed data */
+        dataDescriptor?: {
+            /** Optional data descriptor signature = 0x08074b50 */
+            optionalSignature?: ArrayBuffer;
+            /** CRC-32 of uncompressed data */
+            crc32: number;
+            /** Compressed size */
+            compressedSize: number;
+            /** Uncompressed size */
+            uncompressedSize: number;
+        };
+    };
+    data: {
+        /** Local file header signature = 0x04034b50 (PK♥♦ or "PK\3\4") */
+        signature: ArrayBuffer;
+        /** Version needed to extract (minimum) */
+        versionToExtract: number;
+        /** General purpose bit flag  */
+        generalPurposeBitFlag: number;
+        /** Compression method; e.g. none = 0, DEFLATE = 8 (or "\0x08\0x00") */
+        compressionMethod: number;
+        /** File last modification time (DOS format) */
+        lastModifiedTime: number;
+        /** File last modification date (DOS format) */
+        lastModifiedDate: number;
+        /** CRC-32 of uncompressed data
+         * Value computed over file data by CRC-32 algorithm with
+         * 'magic number' 0xdebb20e3 (little endian)
+         */
+        crc32: number;
+        /** Compressed size (or 0xffffffff for ZIP64) */
+        compressedSize: number;
+        /** Uncompressed size (or 0xffffffff for ZIP64) */
+        uncompressedSize: number;
+        /** File name length (n) */
+        filenameLength: number;
+        /** Extra field length (m) */
+        extraFieldLength: number;
+        /** File name */
+        filename: string;
+        /** Extra field */
+        extraField: ArrayBuffer;
+    };
+}
+/**
+ * A friendly representation of a file inside a ZIP archive
+ */
+export interface RemoteZipFile {
+    /** Full path of the file inside the archive */
+    filename: string;
+    /** Size in bytes */
+    size: number;
+    /** ISO timestamp without timezone (ZIP/DOS does not preserve timezones) */
+    modified: string;
+    /** File attributes of host system */
+    attributes: number;
+}
+/**
+ * An initialised object representating a remote ZIP archive.
+ *
+ * Best constructed from a `RemoteZipPointer`.
+ *
+ * ```ts
+ * import { RemoteZipPointer } from "remote-zip";
+ *
+ * const url = new URL("http://www.example.com/test.zip");
+ * const remoteZip = await new RemoteZipPointer({ url }).populate();
+ * ```
+ */
+export declare class RemoteZip {
+    /** Size of the remote ZIP archive in bytes */
+    contentLength: number;
+    /** URL of the remote ZIP archive */
+    url: URL;
+    /** Records representing the files in the remote ZIP archive */
+    centralDirectoryRecords: CentralDirectoryRecord[];
+    /** Metadata of the remote ZIP archive */
+    endOfCentralDirectory: EndOfCentralDirectory | null;
+    /** HTTP method used to fetch files from the remote ZIP archive */
+    method: string;
+    /** Credentials passed to `fetch` when retrieving files. Defaults to `same-origin`. */
+    credentials: "include" | "omit" | "same-origin";
+    /** Redirect mode passed to `fetch`. Defaults to `"follow"`. */
+    redirect?: RequestRedirect;
+    /** Signal that aborts in-flight requests. */
+    signal?: AbortSignal;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Extra RequestInit merged into every `fetch`. */
+    requestInit?: RequestInit;
+    constructor({ contentLength, url, centralDirectoryRecords, endOfCentralDirectory, method, credentials, redirect, signal, timeoutMs, requestInit, }: {
+        /** Length of the remote ZIP archive in bytes */
+        contentLength: number;
+        /** Passed to fetch when performing a HTTP GET request for the file */
+        url: URL;
+        centralDirectoryRecords: CentralDirectoryRecord[];
+        endOfCentralDirectory: EndOfCentralDirectory | null;
+        /** Passed to fetch when performing a HTTP GET request for the file */
+        method: string;
+        /** Passed to fetch when performing a HTTP GET request for the file. */
+        credentials: "include" | "omit" | "same-origin";
+    } & Pick<RemoteZipRequestOptions, "redirect" | "signal" | "timeoutMs" | "requestInit">);
+    /** Build a fetch RequestInit from this instance's network options. */
+    private requestInitFor;
+    /**
+     * Get a formatted file listing of the remote ZIP archive.
+     *
+     * @returns List of files in the remote ZIP archive.
+     *
+     * ```ts
+     * import { RemoteZipPointer } from "remote-zip";
+     *
+     * const url = new URL("http://www.example.com/test.zip");
+     * const remoteZip = await new RemoteZipPointer({ url }).populate();
+     * const files = remoteZip.files();
+     * // files = [{ attributes: 1107099648, filename: "text.txt", modified: "2021-06-17T12:28:02", size: 14 }]
+     * ```
+     */
+    files(): RemoteZipFile[];
+    /**
+     * Gets a single uncompressed file in the remote ZIP archive.
+     *
+     * @param path Path of the file in the remote ZIP archive
+     * @param additionalHeaders Additional headers, if any, to be passed to the `fetch` request
+     * @param options.maxUncompressedSize If set, inflation aborts and throws once the
+     *   decompressed output would exceed this many bytes. Set this when handling
+     *   untrusted archives to guard against decompression bombs.
+     * @param options.signal Aborts this request (in addition to any instance-level signal).
+     * @param options.timeoutMs Per-request timeout for this fetch.
+     * @param options.verifyCrc If set, verify the decompressed output against the
+     *   entry's CRC-32 and throw a {@link RemoteZipError} (`CRC_MISMATCH`) on mismatch.
+     * @returns Inflated (uncompressed) bytes of the requested file
+     * @throws [RemoteZipError](RemoteZipError) if it fails to parse, fetch, or exceeds limits
+     */
+    fetch(path: string, additionalHeaders?: Headers, options?: EntryDecodeOptions): Promise<Uint8Array>;
+    /**
+     * Decrypt (if needed), decompress, and CRC-verify one entry's bytes. Shared by
+     * {@link fetch} and the encrypted path of {@link fetchStream}.
+     */
+    private decodeEntry;
+    /**
+     * Like {@link fetch}, but returns a `ReadableStream` of the uncompressed bytes
+     * so large entries can be processed incrementally without buffering the whole
+     * file. `maxUncompressedSize` is enforced mid-stream (the stream errors with a
+     * {@link RemoteZipError} once exceeded).
+     *
+     * ```ts
+     * const stream = await remoteZip.fetchStream("big.bin");
+     * for await (const chunk of stream) {
+     *   // process each chunk
+     * }
+     * ```
+     */
+    fetchStream(path: string, additionalHeaders?: Headers, options?: EntryDecodeOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Find an entry, reject encrypted ones, and issue the Range request that covers
+     * its local file header + compressed data. Shared by {@link fetch} and
+     * {@link fetchStream}.
+     */
+    private fetchEntryResponse;
+}
+/**
+ * Network options shared by every request a {@link RemoteZip} / {@link RemoteZipPointer}
+ * makes. All are optional with sensible defaults.
+ */
+export interface RemoteZipRequestOptions {
+    /** HTTP method for the Range GET requests. The metadata probe is always a HEAD. Defaults to `"GET"`. */
+    method?: string;
+    /** Passed to `fetch`. Defaults to `"same-origin"`. */
+    credentials?: "include" | "omit" | "same-origin";
+    /**
+     * Passed to `fetch`. Defaults to `"follow"`. Use `"manual"` or `"error"` to avoid
+     * leaking `Authorization`/cookies cross-origin when a server responds with a redirect.
+     */
+    redirect?: RequestRedirect;
+    /** Aborts in-flight requests when this signal fires. */
+    signal?: AbortSignal;
+    /** Per-request timeout in milliseconds; combined with `signal` via `AbortSignal.any`. */
+    timeoutMs?: number;
+    /** Escape hatch merged into every `fetch` RequestInit (lowest precedence — the options above win). */
+    requestInit?: RequestInit;
+}
+/**
+ * An uninitialised pointer to a remote ZIP file.
+ *
+ * No network requests are sent until `populate()` is called.
+ *
+ * ```ts
+ * const url = new URL("http://www.example.com/test.zip");
+ * const remoteZip = await new RemoteZipPointer({ url }).populate();
+ * const fileListing = remoteZip.files(); // RemoteZipFile[]
+ * const uncompressedBytes = await remoteZip.fetch("test.txt"); // Uint8Array
+ * ```
+ */
+export declare class RemoteZipPointer {
+    /** URL of the remote ZIP archive */
+    url: URL;
+    /** URL used when performing the HTTP HEAD request to fetch ZIP metadata */
+    headUrl: URL;
+    /** Additional headers, if any, passed to `fetch` when calling `url` or `headUrl` */
+    additionalHeaders?: Headers;
+    /** HTTP method used to fetch ZIP metadata (the initial HEAD request is always sent) */
+    method: string;
+    /** Credentials passed to `fetch` when retrieving files. Defaults to `same-origin`. */
+    credentials: "include" | "omit" | "same-origin";
+    /** Redirect mode passed to `fetch`. Defaults to `"follow"`. */
+    redirect?: RequestRedirect;
+    /** Signal that aborts in-flight requests. */
+    signal?: AbortSignal;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+    /** Extra RequestInit merged into every `fetch`. */
+    requestInit?: RequestInit;
+    constructor({ url, headUrl, additionalHeaders, method, credentials, redirect, signal, timeoutMs, requestInit, }: {
+        /** URL for GET requests */
+        url: URL;
+        /** Passed to fetch when performing a HTTP GET request for the file */
+        additionalHeaders?: Headers;
+        /** Passed to fetch when performing a HTTP GET request for the file */
+        method?: string;
+        /** Passed to fetch when performing a HTTP GET request for the file */
+        credentials?: "include" | "omit" | "same-origin";
+        /** URL for HEAD request. Defaults to `url`. This can, for example, differ from `url` if you are using a signed URL for S3. */
+        headUrl?: URL;
+    } & Pick<RemoteZipRequestOptions, "redirect" | "signal" | "timeoutMs" | "requestInit">);
+    /** Build a fetch RequestInit from this pointer's network options. */
+    private requestInitFor;
+    /**
+     * Gets metadata about the ZIP file and constructs an initialised `RemoteZip`.
+     *
+     * @returns An initialised [RemoteZip](RemoteZip)
+     * @throws [RemoteZipError](RemoteZipError) if it fails to parse or fetch
+     */
+    populate(): Promise<RemoteZip>;
+    private fetchEndOfCentralDirectory;
+    private fetchZip64EOCD;
+    private fetchCentralDirectoryRecords;
+}
+/**
+ * Parses DOS datetime into an ISO string without timezone.
+ *
+ * @param zipDate DOS date format
+ * @param zipTime DOS time format
+ * @returns An ISO datetime without timezone. Defaults to `"1980-01-01T00:00:00"` if the datetime is invalid
+ * @see https://github.com/Stuk/jszip/blob/112fcdb9953c6b9a2744afee451d73029f7cd2f8/lib/reader/DataReader.js#L105
+ */
+export declare const parseZipDatetime: (zipDate: number, zipTime: number) => string;
+/**
+ * Detects whether an EOCD record points at ZIP64 structures this library does
+ * not parse yet. Any ZIP64 sentinel value (`0xffff` for 16-bit fields,
+ * `0xffffffff` for 32-bit fields) means the real value lives in a ZIP64 EOCD.
+ */
+export declare const isZip64: (eocd: EndOfCentralDirectory) => boolean;
+/** Effective central-directory location from a ZIP64 End Of Central Directory record. */
+export interface Zip64EndOfCentralDirectory {
+    centralDirectoryRecordCount: number;
+    centralDirectoryByteSize: number;
+    centralDirectoryByteOffset: number;
+}
+/** Locate the ZIP64 EOCD locator in a tail buffer and return the ZIP64 EOCD offset. */
+export declare const parseZip64EOCDLocator: (buffer: ArrayBuffer) => {
+    zip64EOCDOffset: number;
+} | null;
+/** Parse a ZIP64 End Of Central Directory record (the real CD offset/size/count). */
+export declare const parseZip64EOCD: (buffer: ArrayBuffer) => Zip64EndOfCentralDirectory | null;
+/**
+ * Decode a ZIP filename/comment. ZIP entries use CP437 unless general-purpose
+ * bit 11 marks the field as UTF-8; ASCII is identical in both.
+ */
+export declare const decodeZipString: (bytes: ArrayBuffer, utf8: boolean) => string;
+export declare const parseAllCDs: (buffer: ArrayBuffer) => CentralDirectoryRecord[];
+export declare const parseOneCD: (buffer: ArrayBuffer) => CentralDirectoryRecord | null;
+export declare const parseOneEOCD: (buffer: ArrayBuffer) => EndOfCentralDirectory | null;
+export declare const parseOneLocalFile: (buffer: ArrayBuffer, 
+/** Sometimes, the local header does not have the compressed size and a data descriptor is used after the compressed data.
+ * If provided, will be used if the local header indicates a data descriptor block.
+ * It is used to find the correct offset for the data descriptor. */
+compressedSizeOverride?: number) => LocalFileHeader | null;