improve Unix/MS-DOS metadata support

Author: gildas-lormeau

index.d.ts

@@ -986,14 +986,78 @@ export interface EntryMetaData {
    * `true` if `internalFileAttributes` and `externalFileAttributes` are compatible with MS-DOS format.
    */
   msDosCompatible: boolean;
+  /**
+   * Note (MS-DOS / Unix attributes):
+   *
+   * - The single source of truth for on-disk metadata is the 32-bit `externalFileAttributes` value stored in
+   *   the ZIP headers. The upper 16 bits are commonly used for Unix `st_mode` (type/permissions/special bits)
+   *   and the low 8 bits for MS-DOS attribute flags.
+   *
+   * - Writer vs Reader:
+   *   - The writer composes `externalFileAttributes` from the provided options (`externalFileAttributes`,
+   *     `unixMode`/special flags, `msdosAttributesRaw`/`msdosAttributes`).
+   *   - The reader decodes the stored `externalFileAttributes` and exposes convenience fields such as
+   *     `msdosAttributesRaw`, `msdosAttributes`, `unixExternalUpper`, and `unixMode`.
+   *
+   * - Practical rule: treat `externalFileAttributes` as authoritative; other fields are conveniences derived
+   *   from it. If you need a specific on-disk value, set `externalFileAttributes` explicitly.
+   */
+  /**
+   * The MS-DOS attributes low byte (raw).
+   * This is the low 8 bits of {@link EntryMetaData#externalFileAttributes} when present.
+   */
+  msdosAttributesRaw?: number;
+  /**
+   * The MS-DOS attribute flags exposed as booleans.
+   */
+  msdosAttributes?: {
+    readOnly: boolean;
+    hidden: boolean;
+    system: boolean;
+    directory: boolean;
+    archive: boolean;
+  };
+  /**
+   * Unix owner id when available.
+   */
+  uid?: number;
+  /**
+   * Unix group id when available.
+   */
+  gid?: number;
+  /**
+   * Unix mode (st_mode) when available.
+   */
+  unixMode?: number;
+  /**
+   * `true` if the setuid bit is set on the entry.
+   */
+  setuid?: boolean;
+  /**
+   * `true` if the setgid bit is set on the entry.
+   */
+  setgid?: boolean;
+  /**
+   * `true` if the sticky bit is set on the entry.
+   */
+  sticky?: boolean;
   /**
    * The internal file attributes (raw).
    */
   internalFileAttributes: number;
   /**
-   * The external file attributes (raw).
+   * The 32-bit `externalFileAttributes` field is the authoritative on-disk metadata for each entry.
+   * - Upper 16 bits: Unix mode/type (e.g., permissions, file type)
+   * - Low 8 bits: MS-DOS file attributes (e.g., directory, read-only)
+   *
+   * When writing, all provided options are merged into this field. When reading, convenience fields are decoded from it.
+   * For most use cases, prefer the high-level options and fields; only advanced users need to manipulate the raw value directly.
    */
   externalFileAttributes: number;
+  /**
+   * The upper 16-bit portion of {@link EntryMetaData#externalFileAttributes} when it represents Unix mode bits.
+   */
+  unixExternalUpper?: number;
   /**
    * The number of the disk where the entry data starts.
    */
@@ -1478,12 +1542,57 @@ export interface ZipWriterConstructorOptions {
    * @defaultValue 0
    */
   externalFileAttributes?: number;
+  /**
+   * The Unix owner id to write in the Unix extra field or as part of the external attributes.
+   */
+  uid?: number;
+  /**
+   * The Unix group id to write in the Unix extra field or as part of the external attributes.
+   */
+  gid?: number;
+  /**
+   * The Unix mode (st_mode bits) to use when writing external attributes.
+   */
+  unixMode?: number;
+  /**
+   * `true` to set the setuid bit when writing the Unix mode.
+   */
+  setuid?: boolean;
+  /**
+   * `true` to set the setgid bit when writing the Unix mode.
+   */
+  setgid?: boolean;
+  /**
+   * `true` to set the sticky bit when writing the Unix mode.
+   */
+  sticky?: boolean;
+  /**
+   * Which Unix extra field format to write when creating entries that include Unix metadata.
+   * - "infozip": use Info-ZIP New Unix extra field
+   * - "unix": use the traditional Unix extra field format
+   */
+  unixExtraFieldType?: "infozip" | "unix";
   /**
    * The internal file attribute.
    *
    * @defaultValue 0
    */
   internalFileAttributes?: number;
+  /**
+   * When provided, the low 8-bit MS-DOS attributes to write into external file attributes.
+   * Must be an integer between 0 and 255.
+   */
+  msdosAttributesRaw?: number;
+  /**
+   * When provided, MS-DOS attribute flags (boolean object) to write into external file attributes low byte.
+   */
+  msdosAttributes?: {
+    readOnly?: boolean;
+    hidden?: boolean;
+    system?: boolean;
+    directory?: boolean;
+    archive?: boolean;
+  };
   /**
    * `false` to never write disk numbers in zip64 data.
    *

lib/core/constants.js

@@ -58,6 +58,8 @@ const EXTRAFIELD_TYPE_EXTENDED_TIMESTAMP = 0x5455;
 const EXTRAFIELD_TYPE_UNICODE_PATH = 0x7075;
 const EXTRAFIELD_TYPE_UNICODE_COMMENT = 0x6375;
 const EXTRAFIELD_TYPE_USDZ = 0x1986;
+const EXTRAFIELD_TYPE_INFOZIP = 0x7875;
+const EXTRAFIELD_TYPE_UNIX = 0x7855;
 
 const BITFLAG_ENCRYPTED = 0b1;
 const BITFLAG_LEVEL = 0b0110;
@@ -67,10 +69,17 @@ const BITFLAG_LEVEL_SUPER_FAST_MASK = 0b110;
 const BITFLAG_DATA_DESCRIPTOR = 0b1000;
 const BITFLAG_LANG_ENCODING_FLAG = 0b100000000000;
 const FILE_ATTR_MSDOS_DIR_MASK = 0b10000;
+const FILE_ATTR_MSDOS_READONLY_MASK = 0x01;
+const FILE_ATTR_MSDOS_HIDDEN_MASK = 0x02;
+const FILE_ATTR_MSDOS_SYSTEM_MASK = 0x04;
+const FILE_ATTR_MSDOS_ARCHIVE_MASK = 0x20;
 const FILE_ATTR_UNIX_TYPE_MASK = 0o170000;
 const FILE_ATTR_UNIX_TYPE_DIR = 0o040000;
 const FILE_ATTR_UNIX_EXECUTABLE_MASK = 0o111;
 const FILE_ATTR_UNIX_DEFAULT_MASK = 0o644;
+const FILE_ATTR_UNIX_SETUID_MASK = 0o4000;
+const FILE_ATTR_UNIX_SETGID_MASK = 0o2000;
+const FILE_ATTR_UNIX_STICKY_MASK = 0o1000;
 
 const VERSION_DEFLATE = 0x14;
 const VERSION_ZIP64 = 0x2D;
@@ -117,6 +126,8 @@ export {
 	EXTRAFIELD_TYPE_UNICODE_PATH,
 	EXTRAFIELD_TYPE_UNICODE_COMMENT,
 	EXTRAFIELD_TYPE_USDZ,
+	EXTRAFIELD_TYPE_INFOZIP,
+	EXTRAFIELD_TYPE_UNIX,
 	END_OF_CENTRAL_DIR_LENGTH,
 	ZIP64_END_OF_CENTRAL_DIR_LOCATOR_LENGTH,
 	ZIP64_END_OF_CENTRAL_DIR_LENGTH,
@@ -129,10 +140,17 @@ export {
 	BITFLAG_DATA_DESCRIPTOR,
 	BITFLAG_LANG_ENCODING_FLAG,
 	FILE_ATTR_MSDOS_DIR_MASK,
+	FILE_ATTR_MSDOS_READONLY_MASK,
+	FILE_ATTR_MSDOS_HIDDEN_MASK,
+	FILE_ATTR_MSDOS_SYSTEM_MASK,
+	FILE_ATTR_MSDOS_ARCHIVE_MASK,
 	FILE_ATTR_UNIX_TYPE_MASK,
 	FILE_ATTR_UNIX_TYPE_DIR,
 	FILE_ATTR_UNIX_EXECUTABLE_MASK,
 	FILE_ATTR_UNIX_DEFAULT_MASK,
+	FILE_ATTR_UNIX_SETUID_MASK,
+	FILE_ATTR_UNIX_SETGID_MASK,
+	FILE_ATTR_UNIX_STICKY_MASK,
 	VERSION_DEFLATE,
 	VERSION_ZIP64,
 	VERSION_AES,

lib/core/options.js

@@ -55,6 +55,7 @@ const OPTION_SUPPORT_ZIP64_SPLIT_FILE = "supportZip64SplitFile";
 const OPTION_ENCODE_TEXT = "encodeText";
 const OPTION_OFFSET = "offset";
 const OPTION_USDZ = "usdz";
+const OPTION_UNIX_EXTRA_FIELD_TYPE = "unixExtraFieldType";
 
 export {
 	OPTION_FILENAME_ENCODING,
@@ -85,5 +86,6 @@ export {
 	OPTION_SUPPORT_ZIP64_SPLIT_FILE,
 	OPTION_ENCODE_TEXT,
 	OPTION_OFFSET,
-	OPTION_USDZ
+	OPTION_USDZ,
+	OPTION_UNIX_EXTRA_FIELD_TYPE
 };

lib/core/zip-entry.js

@@ -42,6 +42,8 @@ const PROPERTY_NAME_CREATION_DATE = "creationDate";
 const PROPERTY_NAME_RAW_CREATION_DATE = "rawCreationDate";
 const PROPERTY_NAME_INTERNAL_FILE_ATTRIBUTES = "internalFileAttributes";
 const PROPERTY_NAME_EXTERNAL_FILE_ATTRIBUTES = "externalFileAttributes";
+const PROPERTY_NAME_MSDOS_ATTRIBUTES_RAW = "msdosAttributesRaw";
+const PROPERTY_NAME_MSDOS_ATTRIBUTES = "msdosAttributes";
 const PROPERTY_NAME_MS_DOS_COMPATIBLE = "msDosCompatible";
 const PROPERTY_NAME_ZIP64 = "zip64";
 const PROPERTY_NAME_ENCRYPTED = "encrypted";
@@ -53,17 +55,73 @@ const PROPERTY_NAME_EXECUTABLE = "executable";
 const PROPERTY_NAME_COMPRESSION_METHOD = "compressionMethod";
 const PROPERTY_NAME_SIGNATURE = "signature";
 const PROPERTY_NAME_EXTRA_FIELD = "extraField";
+const PROPERTY_NAME_EXTRA_FIELD_INFOZIP = "extraFieldInfoZip";
+const PROPERTY_NAME_EXTRA_FIELD_UNIX = "extraFieldUnix";
+const PROPERTY_NAME_UID = "uid";
+const PROPERTY_NAME_GID = "gid";
+const PROPERTY_NAME_UNIX_MODE = "unixMode";
+const PROPERTY_NAME_SETUID = "setuid";
+const PROPERTY_NAME_SETGID = "setgid";
+const PROPERTY_NAME_STICKY = "sticky";
+const PROPERTY_NAME_BITFLAG = "bitFlag";
+const PROPERTY_NAME_FILENAME_UTF8 = "filenameUTF8";
+const PROPERTY_NAME_COMMENT_UTF8 = "commentUTF8";
+const PROPERTY_NAME_RAW_EXTRA_FIELD = "rawExtraField";
+const PROPERTY_NAME_EXTRA_FIELD_ZIP64 = "extraFieldZip64";
+const PROPERTY_NAME_EXTRA_FIELD_UNICODE_PATH = "extraFieldUnicodePath";
+const PROPERTY_NAME_EXTRA_FIELD_UNICODE_COMMENT = "extraFieldUnicodeComment";
+const PROPERTY_NAME_EXTRA_FIELD_AES = "extraFieldAES";
+const PROPERTY_NAME_EXTRA_FIELD_NTFS = "extraFieldNTFS";
+const PROPERTY_NAME_EXTRA_FIELD_EXTENDED_TIMESTAMP = "extraFieldExtendedTimestamp";
 
 const PROPERTY_NAMES = [
-	PROPERTY_NAME_FILENAME, PROPERTY_NAME_RAW_FILENAME, PROPERTY_NAME_COMPRESSED_SIZE, PROPERTY_NAME_UNCOMPRESSED_SIZE,
-	PROPERTY_NAME_LAST_MODIFICATION_DATE, PROPERTY_NAME_RAW_LAST_MODIFICATION_DATE, PROPERTY_NAME_COMMENT, PROPERTY_NAME_RAW_COMMENT,
-	PROPERTY_NAME_LAST_ACCESS_DATE, PROPERTY_NAME_CREATION_DATE, PROPERTY_NAME_OFFSET, PROPERTY_NAME_DISK_NUMBER_START,
-	PROPERTY_NAME_DISK_NUMBER_START, PROPERTY_NAME_INTERNAL_FILE_ATTRIBUTES,
-	PROPERTY_NAME_EXTERNAL_FILE_ATTRIBUTES, PROPERTY_NAME_MS_DOS_COMPATIBLE, PROPERTY_NAME_ZIP64,
-	PROPERTY_NAME_ENCRYPTED, PROPERTY_NAME_VERSION, PROPERTY_NAME_VERSION_MADE_BY, PROPERTY_NAME_ZIPCRYPTO, PROPERTY_NAME_DIRECTORY,
-	PROPERTY_NAME_EXECUTABLE, PROPERTY_NAME_COMPRESSION_METHOD, PROPERTY_NAME_SIGNATURE, PROPERTY_NAME_EXTRA_FIELD,
-	"bitFlag", "filenameUTF8", "commentUTF8", "rawExtraField", "extraFieldZip64", "extraFieldUnicodePath", "extraFieldUnicodeComment",
-	"extraFieldAES", "extraFieldNTFS", "extraFieldExtendedTimestamp"];
+	PROPERTY_NAME_FILENAME,
+	PROPERTY_NAME_RAW_FILENAME,
+	PROPERTY_NAME_UNCOMPRESSED_SIZE,
+	PROPERTY_NAME_COMPRESSED_SIZE,
+	PROPERTY_NAME_LAST_MODIFICATION_DATE,
+	PROPERTY_NAME_RAW_LAST_MODIFICATION_DATE,
+	PROPERTY_NAME_COMMENT,
+	PROPERTY_NAME_RAW_COMMENT,
+	PROPERTY_NAME_LAST_ACCESS_DATE,
+	PROPERTY_NAME_CREATION_DATE,
+	PROPERTY_NAME_RAW_CREATION_DATE,
+	PROPERTY_NAME_OFFSET,
+	PROPERTY_NAME_DISK_NUMBER_START,
+	PROPERTY_NAME_INTERNAL_FILE_ATTRIBUTES,
+	PROPERTY_NAME_EXTERNAL_FILE_ATTRIBUTES,
+	PROPERTY_NAME_MSDOS_ATTRIBUTES_RAW,
+	PROPERTY_NAME_MSDOS_ATTRIBUTES,
+	PROPERTY_NAME_MS_DOS_COMPATIBLE,
+	PROPERTY_NAME_ZIP64,
+	PROPERTY_NAME_ENCRYPTED,
+	PROPERTY_NAME_VERSION,
+	PROPERTY_NAME_VERSION_MADE_BY,
+	PROPERTY_NAME_ZIPCRYPTO,
+	PROPERTY_NAME_DIRECTORY,
+	PROPERTY_NAME_EXECUTABLE,
+	PROPERTY_NAME_COMPRESSION_METHOD,
+	PROPERTY_NAME_SIGNATURE,
+	PROPERTY_NAME_EXTRA_FIELD,
+	PROPERTY_NAME_EXTRA_FIELD_UNIX,
+	PROPERTY_NAME_EXTRA_FIELD_INFOZIP,
+	PROPERTY_NAME_UID,
+	PROPERTY_NAME_GID,
+	PROPERTY_NAME_UNIX_MODE,
+	PROPERTY_NAME_SETUID,
+	PROPERTY_NAME_SETGID,
+	PROPERTY_NAME_STICKY,
+	PROPERTY_NAME_BITFLAG,
+	PROPERTY_NAME_FILENAME_UTF8,
+	PROPERTY_NAME_COMMENT_UTF8,
+	PROPERTY_NAME_RAW_EXTRA_FIELD,
+	PROPERTY_NAME_EXTRA_FIELD_ZIP64,
+	PROPERTY_NAME_EXTRA_FIELD_UNICODE_PATH,
+	PROPERTY_NAME_EXTRA_FIELD_UNICODE_COMMENT,
+	PROPERTY_NAME_EXTRA_FIELD_AES,
+	PROPERTY_NAME_EXTRA_FIELD_NTFS,
+	PROPERTY_NAME_EXTRA_FIELD_EXTENDED_TIMESTAMP
+];
 
 class Entry {
 
@@ -90,6 +148,8 @@ export {
 	PROPERTY_NAME_RAW_CREATION_DATE,
 	PROPERTY_NAME_INTERNAL_FILE_ATTRIBUTES,
 	PROPERTY_NAME_EXTERNAL_FILE_ATTRIBUTES,
+	PROPERTY_NAME_MSDOS_ATTRIBUTES_RAW,
+	PROPERTY_NAME_MSDOS_ATTRIBUTES,
 	PROPERTY_NAME_MS_DOS_COMPATIBLE,
 	PROPERTY_NAME_ZIP64,
 	PROPERTY_NAME_ENCRYPTED,
@@ -101,5 +161,11 @@ export {
 	PROPERTY_NAME_COMPRESSION_METHOD,
 	PROPERTY_NAME_SIGNATURE,
 	PROPERTY_NAME_EXTRA_FIELD,
+	PROPERTY_NAME_GID,
+	PROPERTY_NAME_UID,
+	PROPERTY_NAME_UNIX_MODE,
+	PROPERTY_NAME_SETUID,
+	PROPERTY_NAME_SETGID,
+	PROPERTY_NAME_STICKY,
 	Entry
 };