@zip.js/zip.js 2.16.0 → 2.17.0

package/index.d.cts

@@ -2009,7 +2009,10 @@ export interface ZipReaderOptions {
    *
    * A signal already aborted when the operation starts rejects it with {@link ERR_ABORTED} as the
    * reason of the `AbortError`, or with `signal.reason` when it is set, without relying on the
-   * `signal` option of `pipeTo` that the oldest supported engines ignore.
+   * `signal` option of `pipeTo` that the oldest supported engines ignore. A signal aborted while the
+   * entry is being read rejects the operation as well, whether its compressed data is still being
+   * consumed or its content still being written; on those engines, the content is written to the end
+   * before the operation is rejected.
    */
   signal?: AbortSignal;
   /**
@@ -2440,13 +2443,21 @@ export interface EntryError extends Error {
    * {@link GetEntriesOptions#strictness}. See {@link ERR_AMBIGUOUS_ARCHIVE} for the values it takes.
    */
   reason?: string;
+  /**
+   * The related {@link ZipEntry} (filesystem API), set with {@link EntryError#entryId} and
+   * {@link EntryError#entryName} when the data of an entry cannot be read while exporting. The error
+   * is the one the reader of the entry raised, rethrown with its `cause` intact, e.g. the codec error
+   * behind {@link ERR_INVALID_COMPRESSED_DATA} for an entry imported from a corrupted zip file.
+   */
+  entry?: ZipEntry;
   /**
    * The id of the related {@link ZipEntry} (filesystem API).
    */
   entryId?: number;
   /**
    * The name of the related {@link ZipEntry}, or of the related `FileSystemHandle` when importing
-   * one (filesystem API). Set by {@link ZipDirectoryEntry#addFileSystemHandle} and
+   * one (filesystem API), relative to the exported entry or to the parent of the handle. Set by the
+   * export methods, {@link ZipDirectoryEntry#addFileSystemHandle} and
    * {@link ZipDirectoryEntry#exportFileSystemHandle}, which rethrow the original error rather than
    * wrapping it, so its `message` stays comparable to the exported `ERR_*` constants.
    */
@@ -2871,6 +2882,13 @@ export interface EntryGetDataOptions
  */
 export interface EntryGetDataCheckPasswordOptions extends EntryGetDataOptions {}
 
+/**
+ * Represents the options passed to `{@link ZipFileEntry}#get*()`.
+ */
+export interface ZipFileEntryGetDataOptions
+  extends EntryGetDataOptions,
+    PasswordCandidatesOptions {}
+
 /**
  * Represents an instance used to create a zipped stream.
  *
@@ -3408,7 +3426,10 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
    *
    * A signal already aborted when the operation starts rejects it with {@link ERR_ABORTED} as the
    * reason of the `AbortError`, or with `signal.reason` when it is set, without relying on the
-   * `signal` option of `pipeTo` that the oldest supported engines ignore.
+   * `signal` option of `pipeTo` that the oldest supported engines ignore. A signal aborted while the
+   * entry is being added rejects the operation as well, whether its content is still being read or
+   * its compressed data still being written; on those engines, the data is written to the end before
+   * the operation is rejected.
    */
   signal?: AbortSignal;
   /**
@@ -3977,7 +3998,7 @@ export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
    * @param options The options.
    * @returns A promise resolving to a `string`.
    */
-  getText(encoding?: string, options?: EntryGetDataOptions): Promise<string>;
+  getText(encoding?: string, options?: ZipFileEntryGetDataOptions): Promise<string>;
   /**
    * Retrieves the content of the entry as a `Blob` instance
    *
@@ -3985,7 +4006,7 @@ export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
    * @param options The options.
    * @returns A promise resolving to a `Blob` instance.
    */
-  getBlob(mimeType?: string, options?: EntryGetDataOptions): Promise<Blob>;
+  getBlob(mimeType?: string, options?: ZipFileEntryGetDataOptions): Promise<Blob>;
   /**
    * Retrieves the content of the entry as as a Data URI `string` encoded in Base64
    *
@@ -3995,7 +4016,7 @@ export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
    */
   getData64URI(
     mimeType?: string,
-    options?: EntryGetDataOptions
+    options?: ZipFileEntryGetDataOptions
   ): Promise<string>;
   /**
    * Retrieves the content of the entry as a `Uint8Array` instance
@@ -4003,7 +4024,7 @@ export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
    * @param options The options.
    * @returns A promise resolving to a `Uint8Array` instance.
    */
-  getUint8Array(options?: EntryGetDataOptions): Promise<Uint8Array>;
+  getUint8Array(options?: ZipFileEntryGetDataOptions): Promise<Uint8Array>;
   /**
    * Retrieves the content of the entry via a `WritableStream` instance
    *
@@ -4013,7 +4034,7 @@ export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
    */
   getWritable(
     writable?: WritableStream,
-    options?: EntryGetDataOptions
+    options?: ZipFileEntryGetDataOptions
   ): Promise<WritableStream>;
   /**
    * Retrieves the content of the entry via a {@link Writer} instance
@@ -4028,7 +4049,7 @@ export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
       | WritableWriter
       | WritableStream
       | AsyncGenerator<Writer<unknown> | WritableWriter | WritableStream>,
-    options?: EntryGetDataOptions
+    options?: ZipFileEntryGetDataOptions
   ): Promise<Type>;
   /**
    * Retrieves the content of the entry as an `ArrayBuffer` instance
@@ -4036,7 +4057,7 @@ export class ZipFileEntry<ReaderType, WriterType> extends ZipEntry {
    * @param options The options.
    * @returns A promise resolving to an `ArrayBuffer` instance.
    */
-  getArrayBuffer(options?: EntryGetDataOptions): Promise<ArrayBuffer>;
+  getArrayBuffer(options?: ZipFileEntryGetDataOptions): Promise<ArrayBuffer>;
   /**
    * Replaces the content of the entry with a `Blob` instance
    *
@@ -4510,11 +4531,89 @@ export class ZipDirectoryEntry extends ZipEntry {
   getExportedSize(options?: ZipDirectoryEntryExportOptions): Promise<number>;
 }
 
+/**
+ * Represents the options supplying several passwords to the entries imported from a zip file, tried in
+ * order when an entry is read.
+ *
+ * @remarks
+ * The core API takes one password per reader or per call. The filesystem API adds a list of
+ * candidates and a function asked for a password when the candidates fail, because it reads each
+ * entry into memory before using it and can therefore try again. The candidates are tried in this
+ * order: the {@link ZipReaderOptions#password} or {@link ZipReaderOptions#rawPassword} option,
+ * then the passwords that already decrypted an entry of the same imported zip file, most recent first,
+ * then the {@link PasswordCandidatesOptions#passwords} option. Each candidate is tried once per entry,
+ * and the entries of a zip file overwhelmingly share one password, so an archive costs one extra
+ * attempt per wrong candidate ahead of the right one, and not one per entry.
+ *
+ * A candidate is rejected when the entry raises an {@link ERR_INVALID_PASSWORD} error, which both
+ * encryption methods do on the first bytes of the entry, before any content is produced. An entry
+ * encrypted with ZipCrypto verifies the password on a single byte, so one wrong password in 256 passes
+ * that check and fails while reading the content instead: for such entries the password is first
+ * verified alone, the CRC32 of the content is then checked whatever the {@link ZipReaderOptions#checkCrc32}
+ * option says, and a read failing with an {@link ERR_INVALID_CRC32}, {@link ERR_INVALID_COMPRESSED_DATA}
+ * or {@link ERR_INVALID_UNCOMPRESSED_SIZE} error is treated as a wrong password and the next candidate is
+ * tried. Any other failure, e.g. a failure of the reader or an {@link ERR_CODEC_OUT_OF_MEMORY} error, is
+ * reported as-is. A corrupted entry read with the right password is reported as a wrong password too,
+ * since nothing tells it from a wrong password passing the check. An entry encrypted with AES verifies
+ * the password on two bytes, so a failure of the read that follows is reported as-is, e.g. as an
+ * {@link ERR_INVALID_AUTHENTICATION_CODE} error.
+ *
+ * The options are set when importing the zip file, in the {@link ZipDirectoryEntryExportOptions#readerOptions}
+ * option of an export, and when reading one entry with `{@link ZipFileEntry}#get*()`. They apply to the
+ * entries imported from a zip file only, and never to the entries read as-is with the
+ * {@link ZipReaderOptions#passThrough} option, which are not decrypted.
+ */
+export interface PasswordCandidatesOptions {
+  /**
+   * The passwords tried in order, after the {@link ZipReaderOptions#password} option and the
+   * passwords already accepted by another entry of the same imported zip file. An empty string is
+   * ignored.
+   *
+   * When every candidate fails, the entry raises an {@link ERR_INVALID_PASSWORD} error whose `cause` is
+   * the error raised by the last candidate, unless the {@link PasswordCandidatesOptions#requestPassword}
+   * option is set.
+   *
+   * A value which is neither an array of strings nor unset throws an {@link ERR_INVALID_PASSWORDS}
+   * error.
+   */
+  passwords?: string[];
+  /**
+   * The function asked for a password when every candidate has failed, or when there is none. It is
+   * called with the entry being read and with the error raised by the last candidate, which is
+   * `undefined` when no candidate was tried, and it can return a promise, e.g. when it prompts the user.
+   *
+   * A string is tried on the entry, and the function is called again when it fails, with the
+   * {@link ERR_INVALID_PASSWORD} error. `undefined` or `null` gives up: the entry raises an
+   * {@link ERR_INVALID_PASSWORD} error whose `cause` is the error raised by the last candidate, or an
+   * {@link ERR_ENCRYPTED} error when no candidate was tried. A value of another type throws an
+   * {@link ERR_INVALID_REQUEST_PASSWORD} error. The
+   * function is not called for the entries whose password is already known.
+   *
+   * When several entries are read concurrently, e.g. by `{@link ZipDirectoryEntry}#export*()` with the
+   * {@link ZipWriterConstructorOptions#bufferedWrite} option, only one call is pending at a time: the
+   * other entries wait for its answer and try it before asking themselves. Cancelling the whole
+   * operation from the function is done with the {@link ZipReaderOptions#signal} option, since giving
+   * up fails the entry being read only.
+   *
+   * A value which is neither a function nor unset throws an {@link ERR_INVALID_REQUEST_PASSWORD}
+   * error.
+   *
+   * @param entry The entry being read.
+   * @param error The error raised by the last candidate, `undefined` when no candidate was tried.
+   * @returns The password to try, or `undefined` to give up.
+   */
+  requestPassword?(
+    entry: FileEntry,
+    error?: Error
+  ): Promise<string | undefined | null> | string | undefined | null;
+}
+
 /**
  * Represents the options passed to `{@link ZipDirectoryEntry}#import*()`.
  */
 export interface ZipDirectoryEntryImportOptions
-  extends Omit<ZipReaderConstructorOptions, "passThrough"> {
+  extends Omit<ZipReaderConstructorOptions, "passThrough">,
+    PasswordCandidatesOptions {
   /**
    * `true` to import the entries of the zip file as-is, without decompressing and decrypting them
    *
@@ -4532,10 +4631,10 @@ export interface ZipDirectoryEntryImportOptions
    * path components ignored when building the tree (e.g. `"a/b.txt"` and `"./a/b.txt"`), or one can be
    * a file and the other a directory holding it (e.g. `"a"` and `"a/b.txt"`).
    *
-   * `"throw"` refuses the zip file with an {@link ERR_DUPLICATE_IMPORTED_ENTRY} error, whose `cause`
-   * property holds the {@link EntryMetaData} instance of the entry that could not be imported. The
-   * filesystem is left unchanged, i.e. the entries imported before the error are removed and the
-   * content held before the import is restored.
+   * `"throw"` refuses the zip file with an {@link ERR_DUPLICATE_IMPORTED_ENTRY} error, whose
+   * `cause.entry` property holds the {@link EntryMetaData} instance of the entry that could not be
+   * imported. The filesystem is left unchanged, i.e. the entries imported before the error are
+   * removed and the content held before the import is restored.
    *
    * `"keep-first"` ignores the entry claiming a node already taken, and `"keep-last"` replaces the
    * entry holding the node, which is the behavior of most zip tools. The entries that do not collide
@@ -4689,7 +4788,7 @@ export interface ZipDirectoryEntryExportOptions
    *
    * A value which is neither an object nor unset throws an {@link ERR_INVALID_READER_OPTIONS} error.
    */
-  readerOptions?: Omit<ZipReaderConstructorOptions, "passThrough"> & { passThrough?: boolean };
+  readerOptions?: Omit<ZipReaderConstructorOptions, "passThrough"> & { passThrough?: boolean } & PasswordCandidatesOptions;
 }
 
 /**
@@ -4700,7 +4799,8 @@ export interface ZipDirectoryEntryExportOptions
  * file it creates and must close it for the data to be written.
  */
 export interface ZipDirectoryEntryExportFileSystemHandleOptions
-  extends EntryGetDataOptions {
+  extends EntryGetDataOptions,
+    PasswordCandidatesOptions {
   /**
    * `true` to write independent files concurrently instead of one after another.
    *
@@ -4722,7 +4822,7 @@ export interface ZipDirectoryEntryExportFileSystemHandleOptions
    *
    * A value which is neither an object nor unset throws an {@link ERR_INVALID_READER_OPTIONS} error.
    */
-  readerOptions?: Omit<ZipReaderConstructorOptions, "passThrough"> & { passThrough?: boolean };
+  readerOptions?: Omit<ZipReaderConstructorOptions, "passThrough"> & { passThrough?: boolean } & PasswordCandidatesOptions;
 }
 
 /**
@@ -4918,6 +5018,12 @@ export const ERR_INVALID_CODEC_MODULE: string;
 /**
  * Invalid CRC-32 checksum error, thrown when the {@link ZipReaderOptions#checkCrc32} option is set and the CRC-32
  * checksum of an entry does not match the value stored in the zip file.
+ *
+ * @remarks
+ * When the inflater verifies the checksum itself, through a gzip trailer that zip.js builds from the stored
+ * CRC-32 and uncompressed size, it rejects the trailer as a whole and its error is kept as the `cause`. A
+ * stored uncompressed size larger than the data therefore raises this error too on that route, whereas a
+ * stored size smaller than the data raises {@link ERR_INVALID_UNCOMPRESSED_SIZE} on every route.
  */
 export const ERR_INVALID_CRC32: string;
 /**
@@ -4926,24 +5032,44 @@ export const ERR_INVALID_CRC32: string;
  */
 export const ERR_INVALID_AUTHENTICATION_CODE: string;
 /**
- * Invalid uncompressed size error
+ * Invalid uncompressed size error, thrown when an entry inflates to more bytes than its stored uncompressed size.
+ *
+ * @remarks
+ * An entry encrypted with AES that stores no CRC-32 (AE-2) and inflated through a gzip container, on a host
+ * whose inflater lacks `"deflate-raw"`, raises this error when it inflates to fewer bytes as well, since the
+ * end of its data is told by the stored size alone.
  */
 export const ERR_INVALID_UNCOMPRESSED_SIZE: string;
 /**
- * Invalid compressed data error
+ * Invalid compressed data error, thrown when the codec rejects the compressed data of an entry.
  *
  * @remarks
- * The way malformed compressed data is reported is not uniform across codec
- * backends. Bytes trailing a complete DEFLATE stream (e.g. a wrong
- * `compressedSize`) are tolerated by the bundled WASM and pure-JS codecs, which
- * decompress the valid data and ignore the extra bytes, but are rejected by the
- * native `DecompressionStream` with its own `TypeError` (on Node,
- * `ERR_TRAILING_JUNK_AFTER_STREAM_END`) rather than this error. Any data that is
- * returned is always validated against the entry's uncompressed size (and CRC
- * when `checkCrc32` is set), so it is never silently truncated; the backends
- * differ only in whether trailing bytes are ignored or raised as an error.
+ * The error is the same whatever inflates the data, and the error the codec raised is kept as its
+ * `cause`: the `TypeError` of a native `DecompressionStream`, whose message depends on the engine,
+ * or the error of the bundled WASM or pure-JS codec. An error raised while reading the data, e.g.
+ * by the reader of the zip file or by the decryption of the entry, is not a codec failure and
+ * reaches the caller unchanged.
+ *
+ * Bytes trailing a complete DEFLATE stream (e.g. a wrong `compressedSize`) are rejected by every
+ * codec, the native `DecompressionStream` (on Node.js, with `ERR_TRAILING_JUNK_AFTER_STREAM_END`
+ * as the `code` of the cause) and the bundled WASM and pure-JS codecs alike. Any data that is
+ * returned is always validated against the entry's uncompressed size (and CRC when
+ * {@link ZipReaderOptions#checkCrc32} is set), so it is never silently truncated.
  */
 export const ERR_INVALID_COMPRESSED_DATA: string;
+/**
+ * Codec out of memory error, thrown when the codec of an entry cannot allocate the memory it needs, e.g. when
+ * the fixed heap of the bundled WASM module is exhausted by too many entries processed concurrently in the same
+ * scope.
+ *
+ * @remarks
+ * The error the codec raised is kept as the `cause`. The failure is recognized by the `code` property of that
+ * error, `"Z_MEM_ERROR"`, which the bundled WASM codec sets and the native `DecompressionStream` of Node.js
+ * would set; a codec reporting the failure without it is reported as {@link ERR_INVALID_COMPRESSED_DATA} when
+ * reading, or with its own error when writing. When writing, only a codec that fails to allocate its state is
+ * reported with this error: a failure while compressing keeps the error of the codec.
+ */
+export const ERR_CODEC_OUT_OF_MEMORY: string;
 /**
  * Invalid password error
  */
@@ -5276,6 +5402,19 @@ export const ERR_UNSUPPORTED_PASS_THROUGH_VALUE: string;
  * unknown property of a `readerOptions` object is still ignored, as everywhere else in the API.
  */
 export const ERR_INVALID_READER_OPTIONS: string;
+/**
+ * Invalid passwords error (thrown by `{@link ZipDirectoryEntry}#import*()`, `{@link ZipDirectoryEntry}#export*()`,
+ * {@link ZipDirectoryEntry#exportFileSystemHandle} and `{@link ZipFileEntry}#get*()` when the
+ * {@link PasswordCandidatesOptions#passwords} option is neither an array of strings nor unset)
+ */
+export const ERR_INVALID_PASSWORDS: string;
+/**
+ * Invalid requestPassword error (thrown by `{@link ZipDirectoryEntry}#import*()`, `{@link ZipDirectoryEntry}#export*()`,
+ * {@link ZipDirectoryEntry#exportFileSystemHandle} and `{@link ZipFileEntry}#get*()` when the
+ * {@link PasswordCandidatesOptions#requestPassword} option is neither a function nor unset, and when it returns a
+ * value which is neither a string, `undefined` nor `null`)
+ */
+export const ERR_INVALID_REQUEST_PASSWORD: string;
 /**
  * Invalid entry error (thrown by {@link ZipWriter#add} when the {@link ZipWriterAddDataOptions#entry} option is
  * neither an entry nor unset)