neozipkit 1.0.2 → 1.0.5

package/dist/browser-umd/index.js

@@ -6139,6 +6139,13 @@ var NeoZipKit = (() => {
     LOCAL_FILE_HEADER: () => LOCAL_FILE_HEADER,
     LOCAL_HDR: () => LOCAL_HDR,
     Logger: () => Logger,
+    META_MANIFEST_JSON: () => META_MANIFEST_JSON,
+    META_TIMESTAMP_NZIP: () => META_TIMESTAMP_NZIP,
+    META_TIMESTAMP_OTS: () => META_TIMESTAMP_OTS,
+    META_TOKEN_NZIP: () => META_TOKEN_NZIP,
+    META_TOKEN_NZIP_LEGACY: () => META_TOKEN_NZIP_LEGACY,
+    META_TS_SUBMIT_NZIP: () => META_TS_SUBMIT_NZIP,
+    META_TS_SUBMIT_OTS: () => META_TS_SUBMIT_OTS,
     NEOZIPKIT_INFO: () => NEOZIPKIT_INFO,
     NEO_CRYPTO_EXTRA_FIELD_SIZE: () => NEO_CRYPTO_EXTRA_FIELD_SIZE,
     NEO_CRYPTO_MAGIC_BYTES: () => NEO_CRYPTO_MAGIC_BYTES,
@@ -6158,12 +6165,27 @@ var NeoZipKit = (() => {
     ZipCrypto: () => ZipCrypto,
     ZipEntry: () => ZipEntry,
     ZipkitBrowser: () => ZipkitBrowser,
+    asciiPathEqualsIgnoreCase: () => asciiPathEqualsIgnoreCase,
+    computeArchiveMerkleRoot: () => computeArchiveMerkleRoot,
+    computeMerkleRootV0FromDigests: () => computeMerkleRootV0FromDigests,
+    computeMerkleRootV1FromContents: () => computeMerkleRootV1FromContents,
+    computeMerkleRootV1FromLeaves: () => computeMerkleRootV1FromLeaves,
     configureLoggerFromEnvironment: () => configureLoggerFromEnvironment,
+    contentDigest: () => contentDigest,
     crc32: () => crc32,
     crc32update: () => crc32update,
+    findReservedMetaEntry: () => findReservedMetaEntry,
     getTypeOf: () => getTypeOf,
+    isMetaInfPath: () => isMetaInfPath,
     isMetadataFile: () => isMetadataFile,
+    isReservedMetaPath: () => isReservedMetaPath,
     isStream: () => isStream,
+    leafHashV0: () => leafHashV0,
+    leafHashV1: () => leafHashV1,
+    matchMerkleRoot: () => matchMerkleRoot,
+    merkleRootFromLeaves: () => merkleRootFromLeaves,
+    normalizeMerklePath: () => normalizeMerklePath,
+    parentHash: () => parentHash,
     readBigUInt64LE: () => readBigUInt64LE,
     sha256: () => sha256,
     uMul: () => uMul
@@ -6231,6 +6253,53 @@ var NeoZipKit = (() => {
     ENCRYPT_FAILED: "Encryption failed"
   };
 
+  // src/core/constants/MetaPaths.ts
+  var META_TOKEN_NZIP = "META-INF/TOKEN.NZIP";
+  var META_TOKEN_NZIP_LEGACY = "META-INF/NZIP.TOKEN";
+  var META_TS_SUBMIT_NZIP = "META-INF/TS-SUBMIT.NZIP";
+  var META_TIMESTAMP_NZIP = "META-INF/TIMESTAMP.NZIP";
+  var META_TS_SUBMIT_OTS = "META-INF/TS-SUBMIT.OTS";
+  var META_TIMESTAMP_OTS = "META-INF/TIMESTAMP.OTS";
+  var META_MANIFEST_JSON = "META-INF/manifest.json";
+  var TIMESTAMP_SUBMITTED = META_TS_SUBMIT_OTS;
+  var TIMESTAMP_METADATA = META_TIMESTAMP_OTS;
+  var TOKENIZED_METADATA = META_TOKEN_NZIP;
+  var RESERVED_CANONICAL = [
+    META_TOKEN_NZIP,
+    META_TOKEN_NZIP_LEGACY,
+    META_TS_SUBMIT_NZIP,
+    META_TIMESTAMP_NZIP,
+    META_TS_SUBMIT_OTS,
+    META_TIMESTAMP_OTS,
+    META_MANIFEST_JSON
+  ];
+  function asciiPathEqualsIgnoreCase(a, b) {
+    if (a.length !== b.length) {
+    }
+    return a.toLowerCase() === b.toLowerCase();
+  }
+  function isMetaInfPath(filename) {
+    return filename.toLowerCase().startsWith("meta-inf/");
+  }
+  function isReservedMetaPath(filename) {
+    const lower = filename.toLowerCase();
+    return RESERVED_CANONICAL.some((c) => c.toLowerCase() === lower);
+  }
+  function findReservedMetaEntry(entries, preferredCanonicalNames) {
+    const preferred = Array.isArray(preferredCanonicalNames) ? preferredCanonicalNames : [preferredCanonicalNames];
+    for (const name of preferred) {
+      const exact = entries.find((e) => e.filename === name);
+      if (exact) return exact;
+    }
+    for (const name of preferred) {
+      const folded = entries.find(
+        (e) => typeof e.filename === "string" && asciiPathEqualsIgnoreCase(e.filename, name)
+      );
+      if (folded) return folded;
+    }
+    return null;
+  }
+
   // src/core/constants/Headers.ts
   var LOCAL_FILE_HEADER = "PK";
   var CENTRAL_FILE_HEADER = "PK
";
@@ -6238,9 +6307,6 @@ var NeoZipKit = (() => {
   var ZIP64_CENTRAL_DIRECTORY_LOCATOR = "PK\x07";
   var ZIP64_CENTRAL_DIRECTORY_END = "PK";
   var DATA_DESCRIPTOR = "PK\x07\b";
-  var TIMESTAMP_SUBMITTED = "META-INF/TS-SUBMIT.OTS";
-  var TIMESTAMP_METADATA = "META-INF/TIMESTAMP.OTS";
-  var TOKENIZED_METADATA = "META-INF/NZIP.TOKEN";
   var LOCAL_HDR = {
     SIZE: 30,
     // LOC header size in bytes
@@ -6481,7 +6547,7 @@ var NeoZipKit = (() => {
     IBM2: 102,
     // IBM S/390 (Z390) - Attribute
     SHA256: 334,
-    // SHA256 "N\01" with 64 bytes (256 bit) of SHA256 hash data
+    // NeoZip Extra Field: 32-byte SHA-256 of uncompressed payload (APPNOTE §5)
     NEO_CRYPTO: 590,
     // NeoEncrypt metadata (see docs/NEO_CRYPTO_FORMAT.md); LE on wire: 4E 02
     POSZIP: 18064,
@@ -7633,7 +7699,13 @@ var NeoZipKit = (() => {
       this.gid = null;
       // Group ID
       this.sha256 = null;
-      // SHA-256 hash of the file
+      // SHA-256 hash of the file (Extra Field 0x014E, bare content digest)
+      /**
+       * APPNOTE §6.3 v1 Merkle leaf: SHA-256(0x00 ‖ uncompressed payload).
+       * In-memory only (not written as a ZIP Extra today). Filled in the same streaming hash
+       * pass as `sha256` during create/extract — never reconstruct by re-reading payload when set.
+       */
+      this.merkleLeafV1 = null;
       // Symbolic link data
       this.isSymlink = false;
       // Entry is a symbolic link
@@ -8557,24 +8629,30 @@ var NeoZipKit = (() => {
       // Incremental hash calculation state (from StreamHashCalculator)
       this.crc32State = ~0;
       this.sha256Hash = null;
+      /** Domain-separated leaf hasher (APPNOTE §6.3): SHA-256(0x00 ‖ payload). */
+      this.merkleLeafHash = null;
       this.useSHA256 = false;
       // Hash accumulation state (from HashAccumulator)
       this.hashes = [];
       this.xorResult = Buffer.alloc(32, 0);
       this.enableAccumulation = false;
-      // Merkle tree state (from MerkleTree)
+      // Merkle tree state (from MerkleTree) — generic digest folding; archive roots use merkle/MerkleRoot.ts
       this.merkleLeaves = [];
       this.merkleLayers = [];
       this.merkleOptions = {
         hashLeaves: false,
-        sortLeaves: true,
-        sortPairs: true,
+        // Archive content roots sort by path in MerkleRoot; generic accumulator keeps insertion order.
+        sortLeaves: false,
+        sortPairs: false,
+        // match APPNOTE v0 odd-leaf rule when used as a generic Bitcoin-style tree
         duplicateOdd: true
       };
       this.useSHA256 = options?.useSHA256 || false;
       this.enableAccumulation = options?.enableAccumulation || false;
       if (this.useSHA256) {
         this.sha256Hash = createHash("sha256");
+        this.merkleLeafHash = createHash("sha256");
+        this.merkleLeafHash.update(Buffer.from([0]));
       }
     }
     // ============================================================================
@@ -8592,6 +8670,9 @@ var NeoZipKit = (() => {
       if (this.sha256Hash) {
         this.sha256Hash.update(chunk);
       }
+      if (this.merkleLeafHash) {
+        this.merkleLeafHash.update(chunk);
+      }
     }
     /**
      * Get final CRC-32 value
@@ -8601,7 +8682,7 @@ var NeoZipKit = (() => {
       return ~this.crc32State >>> 0;
     }
     /**
-     * Get final SHA-256 hash as hex string
+     * Get final SHA-256 hash as hex string (Extra Field 0x014E — bare content digest)
      * @returns SHA-256 hash as hex string, or null if SHA-256 not enabled
      */
     finalizeSHA256() {
@@ -8610,13 +8691,46 @@ var NeoZipKit = (() => {
       }
       return null;
     }
+    /**
+     * Get APPNOTE §6.3 v1 Merkle leaf: SHA-256(0x00 ‖ uncompressed payload) as hex.
+     * Consumes the leaf hasher; call after or instead of finalizeSHA256 for dual streams.
+     */
+    finalizeMerkleLeafV1() {
+      if (this.merkleLeafHash) {
+        return this.merkleLeafHash.digest("hex");
+      }
+      return null;
+    }
+    /**
+     * Apply stream digests to a ZIP entry in one place.
+     *
+     * When SHA-256 was enabled, both Extra Field 0x014E (`sha256`) and the v1 Merkle leaf
+     * (`merkleLeafV1`) are finalized from the **same** chunk stream — no second payload pass.
+     */
+    applyToEntry(entry, options) {
+      if (options.setCrc) {
+        entry.crc = this.finalizeCRC32();
+      }
+      if (options.setSha256) {
+        const digest = this.finalizeSHA256();
+        const leaf = this.finalizeMerkleLeafV1();
+        if (digest) {
+          entry.sha256 = digest;
+        }
+        if (leaf) {
+          entry.merkleLeafV1 = leaf;
+        }
+      }
+    }
     /**
      * Reset the incremental hash calculation state
      */
     reset() {
       this.crc32State = ~0;
-      if (this.sha256Hash) {
+      if (this.useSHA256) {
         this.sha256Hash = createHash("sha256");
+        this.merkleLeafHash = createHash("sha256");
+        this.merkleLeafHash.update(Buffer.from([0]));
       }
     }
     // ============================================================================
@@ -9224,18 +9338,16 @@ var NeoZipKit = (() => {
       const hashCalculator = needsHashCalculation ? new HashCalculator({ useSHA256: options?.useSHA256 && !entry.sha256 || false }) : null;
       if (hashCalculator) {
         hashCalculator.update(data);
-        if (!entry.crc || entry.crc === 0) {
-          entry.crc = hashCalculator.finalizeCRC32();
-        }
-        if (options?.useSHA256 && !entry.sha256) {
-          entry.sha256 = hashCalculator.finalizeSHA256();
-        }
+        hashCalculator.applyToEntry(entry, {
+          setCrc: !entry.crc || entry.crc === 0,
+          setSha256: !!(options?.useSHA256 && !entry.sha256)
+        });
         this.log(`Final hashes: CRC32=0x${entry.crc.toString(16).padStart(8, "0")}, SHA256=${entry.sha256 || "N/A"}`);
       }
       const enc = options?.encryptionMethod;
       const useZipCrypto = enc === "zipcrypto";
-      const useNeo = enc === "neo-aes256";
-      const useAes = options?.password && !useZipCrypto && !useNeo;
+      const useAes = enc === "aes256";
+      const useNeo = !!options?.password && !useZipCrypto && !useAes;
       if (options?.password) {
         const label = useZipCrypto ? "ZipCrypto" : useNeo ? "NeoEncrypt (AES-256)" : "WinZip AES-256";
         this.log(`Encrypting compressed data for entry: ${entry.filename} (method: ${label})`);
@@ -9438,9 +9550,11 @@ var NeoZipKit = (() => {
       entry.uncompressedSize = fileData.length;
       const hashCalculator = new HashCalculator({ useSHA256: cmpOptions?.useSHA256 || false });
       hashCalculator.update(fileData);
-      entry.crc = hashCalculator.finalizeCRC32();
-      if (cmpOptions?.useSHA256) {
-        entry.sha256 = hashCalculator.finalizeSHA256();
+      hashCalculator.applyToEntry(entry, {
+        setCrc: true,
+        setSha256: !!cmpOptions?.useSHA256
+      });
+      if (entry.sha256) {
         this.log(`SHA-256 calculated: ${entry.sha256}`);
       }
       return await this.compressData(entry, fileData, cmpOptions);
@@ -9587,17 +9701,21 @@ var NeoZipKit = (() => {
       } else {
         throw new Error(`Unsupported compression method: ${method}`);
       }
+      const hashCalc = new HashCalculator({ useSHA256: true });
+      hashCalc.update(outBuf);
+      const calculatedCRC = hashCalc.finalizeCRC32();
+      const calculatedHash = hashCalc.finalizeSHA256();
+      const leaf = hashCalc.finalizeMerkleLeafV1();
+      if (leaf) {
+        entry.merkleLeafV1 = leaf;
+      }
       if (!skipHashCheck) {
         if (entry.sha256) {
-          const isValid = this.zipkit.testSHA256(entry, outBuf);
-          if (!isValid) {
+          if (calculatedHash !== entry.sha256) {
             throw new Error(Errors_default.INVALID_SHA256);
           }
-        } else {
-          const isValid = this.zipkit.testCRC32(entry, outBuf);
-          if (!isValid) {
-            throw new Error(Errors_default.INVALID_CRC);
-          }
+        } else if (calculatedCRC !== entry.crc) {
+          throw new Error(Errors_default.INVALID_CRC);
         }
       }
       return outBuf;
@@ -9608,6 +9726,176 @@ var NeoZipKit = (() => {
   var ZipDecompress = _ZipDecompress;
   var ZipDecompress_default = ZipDecompress;
 
+  // src/core/merkle/MerkleRoot.ts
+  var LEAF_DOMAIN = Buffer.from([0]);
+  var NODE_DOMAIN = Buffer.from([1]);
+  function sha2562(data) {
+    const h = createHash("sha256");
+    if (Array.isArray(data)) {
+      for (const part of data) {
+        h.update(part);
+      }
+    } else {
+      h.update(data);
+    }
+    return h.digest();
+  }
+  function asBuffer(data, encoding) {
+    if (typeof data === "string") {
+      return Buffer.from(data, encoding ?? "hex");
+    }
+    return Buffer.isBuffer(data) ? data : Buffer.from(data);
+  }
+  function normalizeMerklePath(path) {
+    let p = path.replace(/\\/g, "/");
+    if (p.startsWith("./")) {
+      p = p.slice(2);
+    }
+    while (p.startsWith("/")) {
+      p = p.slice(1);
+    }
+    if (typeof p.normalize === "function") {
+      p = p.normalize("NFC");
+    }
+    return p;
+  }
+  function pathSortKey(path, algorithm) {
+    const normalized = algorithm === "v1" ? normalizeMerklePath(path) : path;
+    return Buffer.from(normalized, "utf8");
+  }
+  function contentDigest(content) {
+    return sha2562(asBuffer(content));
+  }
+  function leafHashV0(contentOrDigest, isDigest = false) {
+    const buf = asBuffer(contentOrDigest);
+    return isDigest ? buf : sha2562(buf);
+  }
+  function leafHashV1(content) {
+    return sha2562([LEAF_DOMAIN, asBuffer(content)]);
+  }
+  function parentHash(left, right, algorithm) {
+    if (algorithm === "v1") {
+      return sha2562([NODE_DOMAIN, left, right]);
+    }
+    return sha2562([left, right]);
+  }
+  function merkleRootFromLeaves(leaves, algorithm) {
+    if (leaves.length === 0) {
+      return null;
+    }
+    let level = leaves.map((l) => Buffer.from(l));
+    while (level.length > 1) {
+      const next = [];
+      for (let i = 0; i + 1 < level.length; i += 2) {
+        next.push(parentHash(level[i], level[i + 1], algorithm));
+      }
+      if (level.length % 2 === 1) {
+        const last = level[level.length - 1];
+        if (algorithm === "v0") {
+          next.push(parentHash(last, last, algorithm));
+        } else {
+          next.push(last);
+        }
+      }
+      level = next;
+    }
+    return level[0].toString("hex");
+  }
+  function resolveLeaf(entry, algorithm) {
+    if (algorithm === "v0") {
+      if (entry.contentSha256) {
+        const d = asBuffer(entry.contentSha256, typeof entry.contentSha256 === "string" ? "hex" : void 0);
+        if (d.length !== 32) {
+          return null;
+        }
+        return d;
+      }
+      if (entry.content) {
+        return contentDigest(entry.content);
+      }
+      return null;
+    }
+    if (entry.merkleLeafV1) {
+      const d = asBuffer(
+        entry.merkleLeafV1,
+        typeof entry.merkleLeafV1 === "string" ? "hex" : void 0
+      );
+      if (d.length !== 32) {
+        return null;
+      }
+      return d;
+    }
+    if (entry.content) {
+      return leafHashV1(entry.content);
+    }
+    return null;
+  }
+  function computeArchiveMerkleRoot(entries, algorithm = "v1") {
+    const prepared = [];
+    for (const entry of entries) {
+      if (isMetaInfPath(entry.path || "")) {
+        continue;
+      }
+      const leaf = resolveLeaf(entry, algorithm);
+      if (!leaf) {
+        continue;
+      }
+      prepared.push({
+        key: pathSortKey(entry.path || "", algorithm),
+        leaf
+      });
+    }
+    if (prepared.length === 0) {
+      return null;
+    }
+    prepared.sort((a, b) => Buffer.compare(a.key, b.key));
+    return merkleRootFromLeaves(
+      prepared.map((p) => p.leaf),
+      algorithm
+    );
+  }
+  function computeMerkleRootV0FromDigests(entries) {
+    return computeArchiveMerkleRoot(
+      entries.map((e) => ({ path: e.path, contentSha256: e.sha256 })),
+      "v0"
+    );
+  }
+  function computeMerkleRootV1FromContents(entries) {
+    return computeArchiveMerkleRoot(
+      entries.map((e) => ({ path: e.path, content: e.content })),
+      "v1"
+    );
+  }
+  function computeMerkleRootV1FromLeaves(entries) {
+    return computeArchiveMerkleRoot(
+      entries.map((e) => ({ path: e.path, merkleLeafV1: e.merkleLeafV1 })),
+      "v1"
+    );
+  }
+  function matchMerkleRoot(entries, declaredRoot) {
+    const expected = declaredRoot.toLowerCase().replace(/^0x/, "");
+    if (!/^[0-9a-f]{64}$/.test(expected)) {
+      return null;
+    }
+    const hasV1Material = entries.some(
+      (e) => !isMetaInfPath(e.path || "") && (!!e.merkleLeafV1 || !!e.content)
+    );
+    if (hasV1Material) {
+      const v1 = computeArchiveMerkleRoot(entries, "v1");
+      if (v1 && v1 === expected) {
+        return { algorithm: "v1", security: "high" };
+      }
+    }
+    const v0 = computeArchiveMerkleRoot(entries, "v0");
+    if (v0 && v0 === expected) {
+      return { algorithm: "v0", security: "legacy" };
+    }
+    if (hasV1Material) {
+      return null;
+    }
+    return null;
+  }
+
   // src/core/Zipkit.ts
   var Zipkit = class {
     /**
@@ -9827,15 +10115,22 @@ var NeoZipKit = (() => {
       return this.zipEntries;
     }
     /**
-     * Get specific ZIP entry by filename from zipEntries[] array
-     * 
+     * Get specific ZIP entry by filename from zipEntries[] array.
+     * Reserved META-INF paths (APPNOTE §2.3) also match ASCII case-insensitively
+     * when an exact spelling is not found.
+     *
      * @param filename - The name/path of the file/directory to find
      * @returns ZipEntry object if found, null if not found
      */
     getZipEntry(filename) {
       try {
         const centralDir = this.getDirectory();
-        return centralDir.find((entry) => entry.filename === filename) || null;
+        const exact = centralDir.find((entry) => entry.filename === filename);
+        if (exact) return exact;
+        if (isReservedMetaPath(filename)) {
+          return findReservedMetaEntry(centralDir, filename);
+        }
+        return null;
       } catch (error) {
         return null;
       }
@@ -10079,14 +10374,23 @@ var NeoZipKit = (() => {
       return ceBuf;
     }
     /**
-     * Calculate Merkle Root of the ZIP file
-     * 
-     * Excludes metadata files (META-INF) to ensure consistent calculation.
-     * Simply calls getDirectory() and returns null if empty.
-     * 
-     * @returns Merkle root string or null if calculation fails
+     * Calculate Merkle root of archive content (non-META-INF entries).
+     *
+     * Per NEOZIP_APPNOTE.md §6:
+     * - Default **v1**: domain-separated leaves SHA-256(0x00 ‖ uncompressed bytes) and
+     *   SHA-256(0x01 ‖ left ‖ right) parents; paths NFC-normalized before sort.
+     * - Legacy **v0**: bare 0x014E digests as leaves, duplicate-odd pairing, path as stored.
+     *
+     * When only Extra Field digests are available (typical after open), **v1 requires
+     * payload bytes**. This sync method therefore returns null for v1; use
+     * {@link getMerkleRootAsync} (extracts content) or `{ algorithm: 'v0' }`.
+     * When you already hold payloads, use {@link merkleRootFromEntries}.
+     *
+     * @param options.algorithm - `v1` (default) or legacy `v0`
+     * @returns Lowercase hex Merkle root, or null if calculation fails
      */
-    getMerkleRoot() {
+    getMerkleRoot(options) {
+      const algorithm = options?.algorithm ?? "v1";
       let zipEntries;
       try {
         zipEntries = this.getDirectory();
@@ -10098,40 +10402,40 @@ var NeoZipKit = (() => {
       if (!zipEntries || zipEntries.length === 0) {
         return null;
       }
-      const hashAccumulator = new HashCalculator_default({ enableAccumulation: true });
-      const contentEntries = zipEntries.filter((entry) => {
-        const filename = entry.filename || "";
-        return filename !== TIMESTAMP_SUBMITTED && filename !== TIMESTAMP_METADATA && filename !== TOKENIZED_METADATA;
-      });
-      for (const entry of contentEntries) {
-        if (entry.sha256) {
-          const hashBuffer = Buffer.from(entry.sha256, "hex");
-          hashAccumulator.addHash(hashBuffer);
-        }
-      }
-      const merkleRoot = hashAccumulator.merkleRoot();
-      if (!merkleRoot) {
-        return null;
+      const contentEntries = zipEntries.filter((entry) => !isMetaInfPath(entry.filename || ""));
+      if (algorithm === "v0") {
+        const digests = contentEntries.filter((e) => e.sha256).map((e) => ({ path: e.filename || "", sha256: e.sha256 }));
+        return computeMerkleRootV0FromDigests(digests);
+      }
+      if (contentEntries.length > 0 && contentEntries.every((e) => !!e.merkleLeafV1)) {
+        return computeMerkleRootV1FromLeaves(
+          contentEntries.map((e) => ({
+            path: e.filename || "",
+            merkleLeafV1: e.merkleLeafV1
+          }))
+        );
       }
-      return merkleRoot;
+      return null;
     }
     /**
-     * Calculate Merkle Root of the ZIP file asynchronously
-     * 
-     * Excludes metadata files (META-INF) to ensure consistent calculation.
-     * Works with both buffer-based and file-based ZIPs.
-     * 
-     * @returns Promise resolving to Merkle root string or null if calculation fails
+     * Calculate Merkle root (preferred for v1 / new archives).
+     *
+     * **v1 (default):** uses precomputed stream leaves when available; otherwise extracts
+     * each content entry once and folds APPNOTE §6.3 root (no second content hash pass
+     * when extract captures merkleLeafV1).
+     * **v0:** uses Extra Field digests only (no extract), APPNOTE §6.2.
+     *
+     * META-INF/** is excluded. File-streaming mode: use ZipkitNode override (testEntry
+     * pipeline) rather than buffering the whole archive.
+     *
+     * @param options.algorithm - `v1` (default) or legacy `v0`
+     * @returns Promise resolving to lowercase hex root, or null
      */
-    async getMerkleRootAsync() {
+    async getMerkleRootAsync(options) {
+      const algorithm = options?.algorithm ?? "v1";
       let zipEntries = [];
       try {
-        if (this.inBuffer) {
-          zipEntries = this.getDirectory();
-        } else {
-          Logger.error("getMerkleRootAsync() called on file-based ZIP. Use ZipkitServer.getMerkleRootAsync() instead.");
-          return null;
-        }
+        zipEntries = this.getDirectory();
       } catch (error) {
         Logger.error(`Failed to get directory for merkle root calculation: ${error instanceof Error ? error.message : String(error)}`);
         return null;
@@ -10139,22 +10443,60 @@ var NeoZipKit = (() => {
       if (!zipEntries || zipEntries.length === 0) {
         return null;
       }
-      const hashAccumulator = new HashCalculator_default({ enableAccumulation: true });
-      const contentEntries = zipEntries.filter((entry) => {
-        const filename = entry.filename || "";
-        return filename !== TIMESTAMP_SUBMITTED && filename !== TIMESTAMP_METADATA && filename !== TOKENIZED_METADATA;
-      });
+      const contentEntries = zipEntries.filter((entry) => !isMetaInfPath(entry.filename || ""));
+      if (algorithm === "v0") {
+        const digests = contentEntries.filter((e) => e.sha256).map((e) => ({ path: e.filename || "", sha256: e.sha256 }));
+        return computeMerkleRootV0FromDigests(digests);
+      }
+      if (contentEntries.length > 0 && contentEntries.every((e) => !!e.merkleLeafV1)) {
+        return computeMerkleRootV1FromLeaves(
+          contentEntries.map((e) => ({
+            path: e.filename || "",
+            merkleLeafV1: e.merkleLeafV1
+          }))
+        );
+      }
+      if (!this.inBuffer) {
+        Logger.error(
+          "getMerkleRootAsync() called on file-based ZIP without precomputed merkle leaves. Use ZipkitNode (streaming testEntry) or ensure create captured merkleLeafV1."
+        );
+        return null;
+      }
       for (const entry of contentEntries) {
-        if (entry.sha256) {
-          const hashBuffer = Buffer.from(entry.sha256, "hex");
-          hashAccumulator.addHash(hashBuffer);
+        try {
+          const data = await this.extract(entry, false);
+          if (entry.merkleLeafV1) {
+            continue;
+          }
+          if (data === null || data.length === 0) {
+            entry.merkleLeafV1 = leafHashV1(Buffer.alloc(0)).toString("hex");
+          } else {
+            entry.merkleLeafV1 = leafHashV1(data).toString("hex");
+          }
+        } catch (error) {
+          Logger.error(
+            `getMerkleRootAsync(): failed to extract ${entry.filename}: ${error instanceof Error ? error.message : String(error)}`
+          );
+          return null;
         }
       }
-      const merkleRoot = hashAccumulator.merkleRoot();
-      if (!merkleRoot) {
+      if (!contentEntries.every((e) => !!e.merkleLeafV1)) {
         return null;
       }
-      return merkleRoot;
+      return computeMerkleRootV1FromLeaves(
+        contentEntries.map((e) => ({
+          path: e.filename || "",
+          merkleLeafV1: e.merkleLeafV1
+        }))
+      );
+    }
+    /**
+     * Compute Merkle root from known digests and/or payloads (APPNOTE §6).
+     * Prefer this during create when uncompressed bytes are still in hand, or when
+     * stream leaves (`merkleLeafV1`) were already produced.
+     */
+    static merkleRootFromEntries(entries, algorithm = "v1") {
+      return computeArchiveMerkleRoot(entries, algorithm);
     }
   };
   Zipkit.version = NEOZIPKIT_INFO.version;
@@ -10508,7 +10850,7 @@ var NeoZipKit = (() => {
     }
   }
   var isMetadataFile = (filename) => {
-    return filename === TIMESTAMP_SUBMITTED || filename === TIMESTAMP_METADATA || filename === TOKENIZED_METADATA;
+    return isMetaInfPath(filename);
   };
 
   // src/core/components/ProgressTracker.ts
@@ -10727,7 +11069,7 @@ var NeoZipKit = (() => {
   var currentDate = /* @__PURE__ */ new Date();
   var releaseDate = `${String(currentDate.getMonth() + 1).padStart(2, "0")}-${String(currentDate.getDate()).padStart(2, "0")}-${currentDate.getFullYear()}`;
   var VERSION = {
-    number: "1.0.2",
+    number: "1.0.5",
     // packageJson.version
     date: releaseDate
   };
@@ -10845,7 +11187,7 @@ var NeoZipKit = (() => {
       const buffers = [];
       for (const entry of zipEntries) {
         if (!entry.isUpdated) {
-          if (entry.filename === TOKENIZED_METADATA || entry.filename === TIMESTAMP_SUBMITTED || entry.filename === TIMESTAMP_METADATA) {
+          if (isMetaInfPath(entry.filename || "")) {
             entry.isUpdated = true;
           } else {
             const inData = await super.copyEntry(entry);
@@ -10870,7 +11212,7 @@ var NeoZipKit = (() => {
           _onEntryDone(entry, "Written (pre-compressed)");
           continue;
         }
-        if (entry.filename === TOKENIZED_METADATA || entry.filename === TIMESTAMP_SUBMITTED || entry.filename === TIMESTAMP_METADATA) {
+        if (isMetaInfPath(entry.filename || "")) {
           const buffer = Buffer.from(fileBuffer);
           entry.crc = crc32(buffer);
           entry.cmpMethod = 0;
@@ -10911,7 +11253,7 @@ var NeoZipKit = (() => {
      * @returns boolean - True if the file is a metadata file
      */
     isMetadataFile(filename) {
-      return filename === TIMESTAMP_SUBMITTED || filename === TIMESTAMP_METADATA || filename === TOKENIZED_METADATA;
+      return isMetaInfPath(filename);
     }
     // --------------------------------------
     // Helper method: Add a file to the ZIP with compression