@zip.js/zip.js 2.8.43 → 2.8.45

package/index.d.cts

@@ -1164,8 +1164,8 @@ export interface ZipReaderOptions {
    * file header of the entry disagrees with its central directory record in a way that could make other tools
    * (e.g. streaming readers based on local file headers) interpret the entry differently. This detects mismatched
    * filenames, general purpose bit flags (encryption, data descriptor and language encoding flags), compression
-   * methods, signatures and sizes. The extra fields are not compared because the zip specification allows them
-   * to differ.
+   * methods, CRC-32 checksums and sizes. The extra fields are not compared because the zip specification allows
+   * them to differ.
    *
    * @defaultValue false
    */
@@ -1177,7 +1177,24 @@ export interface ZipReaderOptions {
    */
   checkPasswordOnly?: boolean;
   /**
-   * `true` to check the signature of the entry.
+   * `true` to verify the CRC-32 checksum of the entry against the value stored in the zip file. The verification
+   * is run on the decompressed data and covers the whole read pipeline. It also applies to entries encrypted with
+   * AES in AE-1 format. It is skipped for entries in AE-2 format because they store a zeroed CRC-32 value.
+   *
+   * @defaultValue false
+   */
+  checkCrc32?: boolean;
+  /**
+   * `true` to verify the authentication code of entries encrypted with AES. The verification detects encrypted
+   * data tampered or corrupted after the encryption.
+   *
+   * @defaultValue true
+   */
+  checkAuthenticationCode?: boolean;
+  /**
+   * `true` to check the CRC-32 checksum of the entry.
+   *
+   * @deprecated Use {@link ZipReaderOptions#checkCrc32} instead.
    *
    * @defaultValue false
    */
@@ -1261,11 +1278,44 @@ export interface EntryExtraFieldAES extends EntryExtraField {
    * The encryption strength (1, 2 or 3).
    */
   strength?: number;
+  /**
+   * The vendor version (1 for AE-1, 2 for AE-2). Entries in AE-1 format store the CRC-32 checksum of the content,
+   * entries in AE-2 format store a zeroed value.
+   */
+  vendorVersion?: number;
+  /**
+   * The vendor identifier.
+   */
+  vendorId?: number;
   /**
    * The compression method stored in the AES extra field.
    */
   originalCompressionMethod?: number;
 }
+/**
+ * Represents a Unix extra field record storing timestamps: the Info-ZIP Unix type 1 extra field (0x5855),
+ * written notably by macOS Archive Utility and `ditto`, or the PKWARE Unix extra field (0x000d). Both store
+ * the last access/modification dates as 32-bit Unix times, followed by the optional uid/gid in the local
+ * file header.
+ */
+export interface EntryExtraFieldUnixDates extends EntryExtraField {
+  /**
+   * The last access date.
+   */
+  lastAccessDate?: Date;
+  /**
+   * The last modification date.
+   */
+  lastModDate?: Date;
+  /**
+   * The Unix user id.
+   */
+  uid?: number;
+  /**
+   * The Unix group id.
+   */
+  gid?: number;
+}
 /**
  * Represents a Unicode path or comment extra field record of an entry.
  */
@@ -1319,8 +1369,14 @@ export interface LocalDirectory {
    * The extra field.
    */
   extraField?: Map<number, EntryExtraField>;
+  /**
+   * The CRC-32 checksum of the content.
+   */
+  crc32?: number;
   /**
    * The signature (CRC32 checksum) of the content.
+   *
+   * @deprecated Use {@link LocalDirectory#crc32} instead.
    */
   signature?: number;
   /**
@@ -1355,6 +1411,14 @@ export interface LocalDirectory {
    * The Info-ZIP Unix extra field.
    */
   extraFieldInfoZip?: EntryExtraField;
+  /**
+   * The Info-ZIP Unix type 1 extra field (0x5855).
+   */
+  extraFieldUnixType1?: EntryExtraFieldUnixDates;
+  /**
+   * The PKWARE Unix extra field (0x000d).
+   */
+  extraFieldPkwareUnix?: EntryExtraFieldUnixDates;
   /**
    * The extended timestamp extra field.
    */
@@ -1462,9 +1526,17 @@ export interface EntryMetaData {
    */
   commentUTF8: boolean;
   /**
-   * The signature (CRC32 checksum) of the content.
+   * The CRC-32 checksum of the content. It is `undefined` when the zip file does not store it, e.g. for entries
+   * encrypted with AES in AE-2 format.
+   */
+  crc32?: number;
+  /**
+   * The signature (CRC32 checksum) of the content. It is `undefined` for entries encrypted with AES returned by
+   * {@link ZipWriter#add}.
+   *
+   * @deprecated Use {@link EntryMetaData#crc32} instead.
    */
-  signature: number;
+  signature?: number;
   /**
    * The extra field.
    */
@@ -1620,6 +1692,14 @@ export interface EntryMetaData {
    * The Info-ZIP Unix extra field.
    */
   extraFieldInfoZip?: EntryExtraField;
+  /**
+   * The Info-ZIP Unix type 1 extra field (0x5855).
+   */
+  extraFieldUnixType1?: EntryExtraFieldUnixDates;
+  /**
+   * The PKWARE Unix extra field (0x000d).
+   */
+  extraFieldPkwareUnix?: EntryExtraFieldUnixDates;
   /**
    * The extended timestamp extra field.
    */
@@ -1928,15 +2008,29 @@ export interface ZipWriterAddDataOptions
    */
   comment?: string;
   /**
-   * The extra field of the entry.
+   * The extra field of the entry, written in the local file header and the central directory.
    */
   extraField?: Map<number, Uint8Array>;
+  /**
+   * The extra field of the entry written only in the local file header.
+   */
+  localExtraField?: Map<number, Uint8Array>;
   /**
    * The uncompressed size of the entry. This option is ignored if the {@link ZipWriterConstructorOptions#passThrough} option is not set to `true`.
    */
   uncompressedSize?: number;
+  /**
+   * The CRC-32 checksum of the content. This option is ignored if the {@link ZipWriterConstructorOptions#passThrough} option is not set to `true`.
+   *
+   * When the entry is AES-encrypted (see {@link ZipWriterConstructorOptions#encrypted}), setting this option marks the entry as AE-1
+   * and stores the checksum in the entry headers, e.g. when copying an AE-1 entry read with the
+   * {@link ZipReaderOptions#passThrough} option. Otherwise, the entry is marked as AE-2 and the checksum fields are set to 0.
+   */
+  crc32?: number;
   /**
    * The signature (CRC32 checksum) of the content. This option is ignored if the {@link ZipWriterConstructorOptions#passThrough} option is not set to `true`.
+   *
+   * @deprecated Use {@link ZipWriterAddDataOptions#crc32} instead.
    */
   signature?: number;
 }
@@ -2013,6 +2107,13 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   keepOrder?: boolean;
   /**
    * The password used to encrypt the content of the entry.
+   *
+   * @remarks
+   * When a password is set and the {@link ZipWriterConstructorOptions#zipCrypto} option is not set to `true`, the
+   * entry is encrypted in AES AE-2 format: the CRC-32 checksum of the content is stored as `0` so that the zip
+   * file reveals no information about the encrypted content. A stored checksum would allow an attacker to verify
+   * guessed content without knowing the password. The integrity of the data is guaranteed by the authentication
+   * code instead.
    */
   password?: string;
   /**
@@ -2057,7 +2158,7 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   /**
    * `true` to store extended timestamp extra fields.
    *
-   * When set to `false`, the maximum last modification date cannot exceed December 31, 2107 and the maximum accuracy is 2 seconds.
+   * When set to `false`, the maximum last modification date cannot exceed December 31, 2107 and the maximum accuracy is 2 seconds, dates being truncated to the whole second and odd seconds rounded up to the next even second.
    *
    * @defaultValue true
    */
@@ -2935,8 +3036,28 @@ export const ERR_RESERVED_COMPRESSION_METHOD: string;
  * Invalid codec module error
  */
 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
+ * This constant and {@link ERR_INVALID_AUTHENTICATION_CODE} share the same value as {@link ERR_INVALID_SIGNATURE}
+ * for backward compatibility. They will become distinct strings in the next minor version.
+ */
+export const ERR_INVALID_CRC32: string;
+/**
+ * Invalid authentication code error, thrown when the authentication code of an entry encrypted with AES does not
+ * match the encrypted data, e.g. when the data was tampered or corrupted after the encryption.
+ *
+ * @remarks
+ * This constant and {@link ERR_INVALID_CRC32} share the same value as {@link ERR_INVALID_SIGNATURE} for backward
+ * compatibility. They will become distinct strings in the next minor version.
+ */
+export const ERR_INVALID_AUTHENTICATION_CODE: string;
 /**
  * Invalid signature error
+ *
+ * @deprecated Use {@link ERR_INVALID_CRC32} or {@link ERR_INVALID_AUTHENTICATION_CODE} instead.
  */
 export const ERR_INVALID_SIGNATURE: string;
 /**
@@ -2954,7 +3075,7 @@ export const ERR_INVALID_UNCOMPRESSED_SIZE: string;
  * 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 `checkSignature` is set), so it is never silently truncated; the backends
+ * 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.
  */
 export const ERR_INVALID_COMPRESSED_DATA: string;

package/index.d.ts

@@ -1164,8 +1164,8 @@ export interface ZipReaderOptions {
    * file header of the entry disagrees with its central directory record in a way that could make other tools
    * (e.g. streaming readers based on local file headers) interpret the entry differently. This detects mismatched
    * filenames, general purpose bit flags (encryption, data descriptor and language encoding flags), compression
-   * methods, signatures and sizes. The extra fields are not compared because the zip specification allows them
-   * to differ.
+   * methods, CRC-32 checksums and sizes. The extra fields are not compared because the zip specification allows
+   * them to differ.
    *
    * @defaultValue false
    */
@@ -1177,7 +1177,24 @@ export interface ZipReaderOptions {
    */
   checkPasswordOnly?: boolean;
   /**
-   * `true` to check the signature of the entry.
+   * `true` to verify the CRC-32 checksum of the entry against the value stored in the zip file. The verification
+   * is run on the decompressed data and covers the whole read pipeline. It also applies to entries encrypted with
+   * AES in AE-1 format. It is skipped for entries in AE-2 format because they store a zeroed CRC-32 value.
+   *
+   * @defaultValue false
+   */
+  checkCrc32?: boolean;
+  /**
+   * `true` to verify the authentication code of entries encrypted with AES. The verification detects encrypted
+   * data tampered or corrupted after the encryption.
+   *
+   * @defaultValue true
+   */
+  checkAuthenticationCode?: boolean;
+  /**
+   * `true` to check the CRC-32 checksum of the entry.
+   *
+   * @deprecated Use {@link ZipReaderOptions#checkCrc32} instead.
    *
    * @defaultValue false
    */
@@ -1261,11 +1278,44 @@ export interface EntryExtraFieldAES extends EntryExtraField {
    * The encryption strength (1, 2 or 3).
    */
   strength?: number;
+  /**
+   * The vendor version (1 for AE-1, 2 for AE-2). Entries in AE-1 format store the CRC-32 checksum of the content,
+   * entries in AE-2 format store a zeroed value.
+   */
+  vendorVersion?: number;
+  /**
+   * The vendor identifier.
+   */
+  vendorId?: number;
   /**
    * The compression method stored in the AES extra field.
    */
   originalCompressionMethod?: number;
 }
+/**
+ * Represents a Unix extra field record storing timestamps: the Info-ZIP Unix type 1 extra field (0x5855),
+ * written notably by macOS Archive Utility and `ditto`, or the PKWARE Unix extra field (0x000d). Both store
+ * the last access/modification dates as 32-bit Unix times, followed by the optional uid/gid in the local
+ * file header.
+ */
+export interface EntryExtraFieldUnixDates extends EntryExtraField {
+  /**
+   * The last access date.
+   */
+  lastAccessDate?: Date;
+  /**
+   * The last modification date.
+   */
+  lastModDate?: Date;
+  /**
+   * The Unix user id.
+   */
+  uid?: number;
+  /**
+   * The Unix group id.
+   */
+  gid?: number;
+}
 /**
  * Represents a Unicode path or comment extra field record of an entry.
  */
@@ -1319,8 +1369,14 @@ export interface LocalDirectory {
    * The extra field.
    */
   extraField?: Map<number, EntryExtraField>;
+  /**
+   * The CRC-32 checksum of the content.
+   */
+  crc32?: number;
   /**
    * The signature (CRC32 checksum) of the content.
+   *
+   * @deprecated Use {@link LocalDirectory#crc32} instead.
    */
   signature?: number;
   /**
@@ -1355,6 +1411,14 @@ export interface LocalDirectory {
    * The Info-ZIP Unix extra field.
    */
   extraFieldInfoZip?: EntryExtraField;
+  /**
+   * The Info-ZIP Unix type 1 extra field (0x5855).
+   */
+  extraFieldUnixType1?: EntryExtraFieldUnixDates;
+  /**
+   * The PKWARE Unix extra field (0x000d).
+   */
+  extraFieldPkwareUnix?: EntryExtraFieldUnixDates;
   /**
    * The extended timestamp extra field.
    */
@@ -1462,9 +1526,17 @@ export interface EntryMetaData {
    */
   commentUTF8: boolean;
   /**
-   * The signature (CRC32 checksum) of the content.
+   * The CRC-32 checksum of the content. It is `undefined` when the zip file does not store it, e.g. for entries
+   * encrypted with AES in AE-2 format.
+   */
+  crc32?: number;
+  /**
+   * The signature (CRC32 checksum) of the content. It is `undefined` for entries encrypted with AES returned by
+   * {@link ZipWriter#add}.
+   *
+   * @deprecated Use {@link EntryMetaData#crc32} instead.
    */
-  signature: number;
+  signature?: number;
   /**
    * The extra field.
    */
@@ -1620,6 +1692,14 @@ export interface EntryMetaData {
    * The Info-ZIP Unix extra field.
    */
   extraFieldInfoZip?: EntryExtraField;
+  /**
+   * The Info-ZIP Unix type 1 extra field (0x5855).
+   */
+  extraFieldUnixType1?: EntryExtraFieldUnixDates;
+  /**
+   * The PKWARE Unix extra field (0x000d).
+   */
+  extraFieldPkwareUnix?: EntryExtraFieldUnixDates;
   /**
    * The extended timestamp extra field.
    */
@@ -1928,15 +2008,29 @@ export interface ZipWriterAddDataOptions
    */
   comment?: string;
   /**
-   * The extra field of the entry.
+   * The extra field of the entry, written in the local file header and the central directory.
    */
   extraField?: Map<number, Uint8Array>;
+  /**
+   * The extra field of the entry written only in the local file header.
+   */
+  localExtraField?: Map<number, Uint8Array>;
   /**
    * The uncompressed size of the entry. This option is ignored if the {@link ZipWriterConstructorOptions#passThrough} option is not set to `true`.
    */
   uncompressedSize?: number;
+  /**
+   * The CRC-32 checksum of the content. This option is ignored if the {@link ZipWriterConstructorOptions#passThrough} option is not set to `true`.
+   *
+   * When the entry is AES-encrypted (see {@link ZipWriterConstructorOptions#encrypted}), setting this option marks the entry as AE-1
+   * and stores the checksum in the entry headers, e.g. when copying an AE-1 entry read with the
+   * {@link ZipReaderOptions#passThrough} option. Otherwise, the entry is marked as AE-2 and the checksum fields are set to 0.
+   */
+  crc32?: number;
   /**
    * The signature (CRC32 checksum) of the content. This option is ignored if the {@link ZipWriterConstructorOptions#passThrough} option is not set to `true`.
+   *
+   * @deprecated Use {@link ZipWriterAddDataOptions#crc32} instead.
    */
   signature?: number;
 }
@@ -2013,6 +2107,13 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   keepOrder?: boolean;
   /**
    * The password used to encrypt the content of the entry.
+   *
+   * @remarks
+   * When a password is set and the {@link ZipWriterConstructorOptions#zipCrypto} option is not set to `true`, the
+   * entry is encrypted in AES AE-2 format: the CRC-32 checksum of the content is stored as `0` so that the zip
+   * file reveals no information about the encrypted content. A stored checksum would allow an attacker to verify
+   * guessed content without knowing the password. The integrity of the data is guaranteed by the authentication
+   * code instead.
    */
   password?: string;
   /**
@@ -2057,7 +2158,7 @@ export interface ZipWriterConstructorOptions extends WorkerConfiguration {
   /**
    * `true` to store extended timestamp extra fields.
    *
-   * When set to `false`, the maximum last modification date cannot exceed December 31, 2107 and the maximum accuracy is 2 seconds.
+   * When set to `false`, the maximum last modification date cannot exceed December 31, 2107 and the maximum accuracy is 2 seconds, dates being truncated to the whole second and odd seconds rounded up to the next even second.
    *
    * @defaultValue true
    */
@@ -2935,8 +3036,28 @@ export const ERR_RESERVED_COMPRESSION_METHOD: string;
  * Invalid codec module error
  */
 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
+ * This constant and {@link ERR_INVALID_AUTHENTICATION_CODE} share the same value as {@link ERR_INVALID_SIGNATURE}
+ * for backward compatibility. They will become distinct strings in the next minor version.
+ */
+export const ERR_INVALID_CRC32: string;
+/**
+ * Invalid authentication code error, thrown when the authentication code of an entry encrypted with AES does not
+ * match the encrypted data, e.g. when the data was tampered or corrupted after the encryption.
+ *
+ * @remarks
+ * This constant and {@link ERR_INVALID_CRC32} share the same value as {@link ERR_INVALID_SIGNATURE} for backward
+ * compatibility. They will become distinct strings in the next minor version.
+ */
+export const ERR_INVALID_AUTHENTICATION_CODE: string;
 /**
  * Invalid signature error
+ *
+ * @deprecated Use {@link ERR_INVALID_CRC32} or {@link ERR_INVALID_AUTHENTICATION_CODE} instead.
  */
 export const ERR_INVALID_SIGNATURE: string;
 /**
@@ -2954,7 +3075,7 @@ export const ERR_INVALID_UNCOMPRESSED_SIZE: string;
  * 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 `checkSignature` is set), so it is never silently truncated; the backends
+ * 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.
  */
 export const ERR_INVALID_COMPRESSED_DATA: string;