neozipkit 1.0.2 → 1.0.5

package/src/core/merkle/MerkleRoot.ts

@@ -0,0 +1,312 @@
+// ======================================
+//  MerkleRoot.ts — NeoZip APPNOTE §6
+//  v0 (legacy Bitcoin-style) and v1 (RFC 6962–style domain separation)
+// ======================================
+
+import * as crypto from 'crypto';
+import { isMetaInfPath } from '../constants/MetaPaths';
+
+/** Merkle algorithms defined in NEOZIP_APPNOTE.md §6. */
+export type MerkleAlgorithm = 'v0' | 'v1';
+
+export interface MerkleContentEntry {
+  /** Central-directory path (UTF-8 string as stored or as known to the writer). */
+  path: string;
+  /**
+   * Uncompressed payload bytes (same bytes hashed into Extra Field 0x014E).
+   * Required for **v1** leaves when `merkleLeafV1` is absent. Optional for **v0** when `contentSha256` is set.
+   */
+  content?: Buffer | Uint8Array;
+  /**
+   * Bare SHA-256 of uncompressed payload (= Extra Field 0x014E), hex or 32-byte Buffer.
+   * Used as v0 leaf; for v1 this alone is **not** a leaf (see APPNOTE §6.3).
+   */
+  contentSha256?: string | Buffer;
+  /**
+   * Precomputed APPNOTE §6.3 v1 leaf: SHA-256(0x00 ‖ uncompressed_bytes), hex or 32-byte Buffer.
+   * Produced in the same streaming pass as `contentSha256` (create/extract via HashCalculator).
+   * Preferred for v1 when present — no second content read.
+   */
+  merkleLeafV1?: string | Buffer;
+}
+
+const LEAF_DOMAIN = Buffer.from([0x00]);
+const NODE_DOMAIN = Buffer.from([0x01]);
+
+function sha256(data: Buffer | Uint8Array | Buffer[]): Buffer {
+  const h = crypto.createHash('sha256');
+  if (Array.isArray(data)) {
+    for (const part of data) {
+      h.update(part);
+    }
+  } else {
+    h.update(data);
+  }
+  return h.digest();
+}
+
+function asBuffer(data: Buffer | Uint8Array | string, encoding?: BufferEncoding): Buffer {
+  if (typeof data === 'string') {
+    return Buffer.from(data, encoding ?? 'hex');
+  }
+  return Buffer.isBuffer(data) ? data : Buffer.from(data);
+}
+
+/**
+ * Normalize a ZIP entry path for v1 leaf ordering (APPNOTE §6.3):
+ * POSIX separators, strip leading `./` and `/`, Unicode NFC, UTF-8 byte order when compared.
+ */
+export function normalizeMerklePath(path: string): string {
+  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;
+}
+
+/** Sort key for path comparison (UTF-8 byte order). */
+function pathSortKey(path: string, algorithm: MerkleAlgorithm): Buffer {
+  const normalized = algorithm === 'v1' ? normalizeMerklePath(path) : path;
+  return Buffer.from(normalized, 'utf8');
+}
+
+/** Bare content digest (= 0x014E value). */
+export function contentDigest(content: Buffer | Uint8Array): Buffer {
+  return sha256(asBuffer(content));
+}
+
+/**
+ * v0 leaf: SHA-256(uncompressed bytes) — same as Extra Field 0x014E.
+ */
+export function leafHashV0(contentOrDigest: Buffer | Uint8Array, isDigest = false): Buffer {
+  const buf = asBuffer(contentOrDigest);
+  return isDigest ? buf : sha256(buf);
+}
+
+/**
+ * v1 leaf: SHA-256(0x00 ‖ uncompressed_bytes).
+ * Must not be confused with the bare 0x014E digest (APPNOTE §6.3).
+ */
+export function leafHashV1(content: Buffer | Uint8Array): Buffer {
+  return sha256([LEAF_DOMAIN, asBuffer(content)]);
+}
+
+/**
+ * Parent node hashes.
+ * v0: SHA-256(H_left ‖ H_right) — order preserved, no pair sorting.
+ * v1: SHA-256(0x01 ‖ H_left ‖ H_right).
+ */
+export function parentHash(left: Buffer, right: Buffer, algorithm: MerkleAlgorithm): Buffer {
+  if (algorithm === 'v1') {
+    return sha256([NODE_DOMAIN, left, right]);
+  }
+  return sha256([left, right]);
+}
+
+/**
+ * Fold an ordered list of leaf hashes into a single root (hex lowercase).
+ * Odd-count rule:
+ *  - v0: duplicate last leaf (Bitcoin-style)
+ *  - v1: promote last node unhashed (RFC 6962–style)
+ */
+export function merkleRootFromLeaves(leaves: Buffer[], algorithm: MerkleAlgorithm): string | null {
+  if (leaves.length === 0) {
+    return null;
+  }
+
+  let level: Buffer[] = leaves.map((l) => Buffer.from(l));
+
+  while (level.length > 1) {
+    const next: Buffer[] = [];
+    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') {
+        // Duplicate last leaf, then hash the pair
+        next.push(parentHash(last, last, algorithm));
+      } else {
+        // Promote unhashed
+        next.push(last);
+      }
+    }
+    level = next;
+  }
+
+  return level[0].toString('hex');
+}
+
+function resolveLeaf(
+  entry: MerkleContentEntry,
+  algorithm: MerkleAlgorithm
+): Buffer | null {
+  if (algorithm === 'v0') {
+    if (entry.contentSha256) {
+      const d = asBuffer(entry.contentSha256, typeof entry.contentSha256 === 'string' ? 'hex' : undefined);
+      if (d.length !== 32) {
+        return null;
+      }
+      return d;
+    }
+    if (entry.content) {
+      return contentDigest(entry.content);
+    }
+    return null;
+  }
+
+  // v1: prefer precomputed domain-separated leaf from the same hashing pass as 0x014E
+  if (entry.merkleLeafV1) {
+    const d = asBuffer(
+      entry.merkleLeafV1,
+      typeof entry.merkleLeafV1 === 'string' ? 'hex' : undefined
+    );
+    if (d.length !== 32) {
+      return null;
+    }
+    return d;
+  }
+  // Domain-separated hash of uncompressed payload (re-hash only if leaf not available)
+  if (entry.content) {
+    return leafHashV1(entry.content);
+  }
+  return null;
+}
+
+/**
+ * Compute archive Merkle root per APPNOTE §6 from content entries
+ * (caller already excluded META-INF/** if desired).
+ *
+ * @returns lowercase hex root, or null if no usable leaves
+ */
+export function computeArchiveMerkleRoot(
+  entries: MerkleContentEntry[],
+  algorithm: MerkleAlgorithm = 'v1'
+): string | null {
+  const prepared: { key: Buffer; leaf: Buffer }[] = [];
+
+  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
+  );
+}
+
+/**
+ * Build v0 root from path + bare content digests only (0x014E extras).
+ * Path order: central-directory bytes as stored (no NFC / strip).
+ */
+export function computeMerkleRootV0FromDigests(
+  entries: Array<{ path: string; sha256: string | Buffer }>
+): string | null {
+  return computeArchiveMerkleRoot(
+    entries.map((e) => ({ path: e.path, contentSha256: e.sha256 })),
+    'v0'
+  );
+}
+
+/**
+ * Build v1 root from path + uncompressed payloads (APPNOTE §6.3).
+ * Paths are normalized before sorting.
+ */
+export function computeMerkleRootV1FromContents(
+  entries: Array<{ path: string; content: Buffer | Uint8Array }>
+): string | null {
+  return computeArchiveMerkleRoot(
+    entries.map((e) => ({ path: e.path, content: e.content })),
+    'v1'
+  );
+}
+
+/**
+ * Build v1 root from path + precomputed domain-separated leaves (APPNOTE §6.3).
+ * Prefer this after create/extract when HashCalculator produced merkleLeafV1 in one stream pass.
+ */
+export function computeMerkleRootV1FromLeaves(
+  entries: Array<{ path: string; merkleLeafV1: string | Buffer }>
+): string | null {
+  return computeArchiveMerkleRoot(
+    entries.map((e) => ({ path: e.path, merkleLeafV1: e.merkleLeafV1 })),
+    'v1'
+  );
+}
+
+/**
+ * Verify a declared root (APPNOTE §6.4): try v1 first (when content or leaves available),
+ * then v0 digests. Returns which algorithm matched, or null on failure.
+ *
+ * When only bare 0x014E digests are available, only v0 can match APPNOTE correctly.
+ * Pass `merkleLeafV1` or content for full v1 verification without re-hashing from scratch
+ * when leaves were computed in the decompress stream.
+ */
+export function matchMerkleRoot(
+  entries: MerkleContentEntry[],
+  declaredRoot: string
+): { algorithm: MerkleAlgorithm; security: 'high' | 'legacy' } | null {
+  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 v1 was not tried (no leaves/content), v0 was the only attempt.
+  if (hasV1Material) {
+    return null;
+  }
+
+  return null;
+}
+
+export default {
+  normalizeMerklePath,
+  contentDigest,
+  leafHashV0,
+  leafHashV1,
+  parentHash,
+  merkleRootFromLeaves,
+  computeArchiveMerkleRoot,
+  computeMerkleRootV0FromDigests,
+  computeMerkleRootV1FromContents,
+  computeMerkleRootV1FromLeaves,
+  matchMerkleRoot,
+};

package/src/core/version.ts

@@ -28,6 +28,6 @@ const currentDate = new Date();
 const releaseDate = `${String(currentDate.getMonth() + 1).padStart(2, '0')}-${String(currentDate.getDate()).padStart(2, '0')}-${currentDate.getFullYear()}`;
 
 export const VERSION = {
-  number: '1.0.2', // packageJson.version
+  number: '1.0.5', // packageJson.version
   date: releaseDate
 }; 

package/src/node/ZipCompressNode.ts

@@ -119,12 +119,10 @@ export class ZipCompressNode {
     
     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),
+          });
     }
     
     // Compress based on method
@@ -148,10 +146,11 @@ export class ZipCompressNode {
       const enc = options.encryptionMethod;
       if (enc === 'zipcrypto') {
         buffer = this.encryptCompressedData(buffer, entry, options.password);
-      } else if (enc === 'neo-aes256') {
-        buffer = this.encryptCompressedDataNeo(buffer, entry, options.password);
-      } else {
+      } else if (enc === 'aes256') {
         buffer = this.encryptCompressedDataAes(buffer, entry, options.password);
+      } else {
+        // Default / 'neo-aes256': NeoEncrypt (0x024E)
+        buffer = this.encryptCompressedDataNeo(buffer, entry, options.password);
       }
     }
 
@@ -187,12 +186,10 @@ export class ZipCompressNode {
         // For buffer, calculate hashes if needed
         if (hashCalculator && entry) {
           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),
+          });
         }
         return data;
       } else {
@@ -219,12 +216,10 @@ export class ZipCompressNode {
         
         // Finalize hashes
         if (hashCalculator && entry) {
-          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),
+          });
         }
         
         return Buffer.alloc(0);
@@ -245,10 +240,10 @@ export class ZipCompressNode {
         if (hashCalculator && entry) {
           hashCalculator.update(data);
           // Always set CRC if hash calculator was used (it calculated the correct CRC)
-          entry.crc = hashCalculator.finalizeCRC32();
-          if (options?.useSHA256 && !entry.sha256) {
-            entry.sha256 = hashCalculator.finalizeSHA256();
-          }
+          hashCalculator.applyToEntry(entry, {
+          setCrc: true,
+          setSha256: !!(options?.useSHA256 && !entry.sha256),
+        });
         }
         
         const result = pako.deflateRaw(data, { level: level ?? 6 });
@@ -298,10 +293,10 @@ export class ZipCompressNode {
         // Finalize hashes after all chunks processed and compressed
         if (hashCalculator && entry) {
           // Always set CRC if hash calculator was used (it calculated the correct CRC)
-          entry.crc = hashCalculator.finalizeCRC32();
-          if (options?.useSHA256 && !entry.sha256) {
-            entry.sha256 = hashCalculator.finalizeSHA256();
-          }
+          hashCalculator.applyToEntry(entry, {
+          setCrc: true,
+          setSha256: !!(options?.useSHA256 && !entry.sha256),
+        });
         }
         
         // For chunked processing, return empty buffer (data already written via onOutputBuffer)
@@ -375,12 +370,10 @@ export class ZipCompressNode {
       if (isBuffer) {
         if (hashCalculator && entry) {
           hashCalculator.update(input);
-          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),
+          });
         }
         return input;
       }
@@ -405,12 +398,10 @@ export class ZipCompressNode {
         position += chunk.length;
       }
       if (hashCalculator && entry) {
-        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),
+          });
       }
       return onOutputBuffer ? Buffer.alloc(0) : Buffer.concat(chunks);
     }
@@ -430,10 +421,10 @@ export class ZipCompressNode {
 
       if (isBuffer && hashCalculator && entry) {
         hashCalculator.update(input);
-        entry.crc = hashCalculator.finalizeCRC32();
-        if (options?.useSHA256 && !entry.sha256) {
-          entry.sha256 = hashCalculator.finalizeSHA256();
-        }
+        hashCalculator.applyToEntry(entry, {
+          setCrc: true,
+          setSha256: !!(options?.useSHA256 && !entry.sha256),
+        });
       }
 
       const collected: Buffer[] = [];
@@ -457,10 +448,10 @@ export class ZipCompressNode {
       );
 
       if (!isBuffer && hashCalculator && entry) {
-        entry.crc = hashCalculator.finalizeCRC32();
-        if (options?.useSHA256 && !entry.sha256) {
-          entry.sha256 = hashCalculator.finalizeSHA256();
-        }
+        hashCalculator.applyToEntry(entry, {
+          setCrc: true,
+          setSha256: !!(options?.useSHA256 && !entry.sha256),
+        });
       }
       if (entry) {
         entry.compressedSize = compressedSize;

package/src/node/ZipDecompressNode.ts

@@ -451,6 +451,8 @@ export class ZipDecompressNode {
       if (!options?.skipHashCheck) {
         if (entry.sha256) {
           const calculatedHash = hashCalc.finalizeSHA256();
+          const leaf = hashCalc.finalizeMerkleLeafV1();
+          if (leaf) entry.merkleLeafV1 = leaf;
           this.log(`SHA-256 comparison: calculated=${calculatedHash}, stored=${entry.sha256}`);
           if (calculatedHash !== entry.sha256) {
             if (options?.outputPath && fs) {
@@ -540,6 +542,8 @@ export class ZipDecompressNode {
       if (!options?.skipHashCheck) {
         if (entry.sha256) {
           const calculatedHash = hashCalc.finalizeSHA256();
+          const leaf = hashCalc.finalizeMerkleLeafV1();
+          if (leaf) entry.merkleLeafV1 = leaf;
           this.log(`SHA-256 comparison: calculated=${calculatedHash}, stored=${entry.sha256}`);
           if (calculatedHash !== entry.sha256) {
             throw new Error(Errors.INVALID_SHA256);
@@ -607,6 +611,8 @@ export class ZipDecompressNode {
       if (!options?.skipHashCheck) {
         if (entry.sha256) {
           const calculatedHash = hashCalc.finalizeSHA256();
+          const leaf = hashCalc.finalizeMerkleLeafV1();
+          if (leaf) entry.merkleLeafV1 = leaf;
           this.log(`SHA-256 comparison: calculated=${calculatedHash}, stored=${entry.sha256}`);
           if (calculatedHash !== entry.sha256) {
             throw new Error(Errors.INVALID_SHA256);
@@ -625,7 +631,13 @@ export class ZipDecompressNode {
           return { verifiedHash: undefined };
         }
       } else {
-        // Hash check skipped - return undefined
+        // Hash check skipped — still finalize leaf/digest once from this stream when SHA was enabled
+        if (entry.sha256 && hashCalc) {
+          const calculatedHash = hashCalc.finalizeSHA256();
+          const leaf = hashCalc.finalizeMerkleLeafV1();
+          if (leaf) entry.merkleLeafV1 = leaf;
+          return { verifiedHash: calculatedHash || undefined };
+        }
         return { verifiedHash: undefined };
       }
     } catch (error) {

package/src/node/ZipkitNode.ts

@@ -27,6 +27,12 @@ import {
 import * as fs from 'fs';
 import * as path from 'path';
 import { minimatch } from 'minimatch';
+import {
+  computeMerkleRootV0FromDigests,
+  computeMerkleRootV1FromLeaves,
+  type MerkleAlgorithm,
+} from '../core/merkle/MerkleRoot';
+import { isMetaInfPath } from '../core/constants/MetaPaths';
 
 // Re-export everything from core Zipkit
 export * from '../core';
@@ -111,6 +117,79 @@ export default class ZipkitNode extends Zipkit {
     return this._zipkitDeCmpNode;
   }
 
+  /**
+   * Streaming Merkle root for file-based archives.
+   * V1 leaves come from the same decompress→hash pass as integrity (testEntry / extract),
+   * chunked — never re-reads uncompressed sources or materializes whole entries for the root alone.
+   */
+  async getMerkleRootAsync(options?: { algorithm?: MerkleAlgorithm }): Promise<string | null> {
+    const algorithm: MerkleAlgorithm = options?.algorithm ?? 'v1';
+    let zipEntries: ZipEntry[];
+    try {
+      zipEntries = this.getDirectory();
+    } catch {
+      return null;
+    }
+    if (!zipEntries?.length) {
+      return null;
+    }
+
+    const contentEntries = zipEntries.filter((e) => !isMetaInfPath(e.filename || ''));
+    if (contentEntries.length === 0) {
+      return null;
+    }
+
+    if (algorithm === 'v0') {
+      const digests = contentEntries
+        .filter((e) => e.sha256)
+        .map((e) => ({ path: e.filename || '', sha256: e.sha256 as string }));
+      return computeMerkleRootV0FromDigests(digests);
+    }
+
+    if (contentEntries.every((e) => !!e.merkleLeafV1)) {
+      return computeMerkleRootV1FromLeaves(
+        contentEntries.map((e) => ({
+          path: e.filename || '',
+          merkleLeafV1: e.merkleLeafV1 as string,
+        }))
+      );
+    }
+
+    // Buffer-loaded: base class extract path
+    if ((this as any).inBuffer) {
+      return super.getMerkleRootAsync(options);
+    }
+
+    // File-based: stream hash each content entry once via testEntry (no write, dual hash)
+    if (!this.fileHandle && !this.filePath) {
+      // Create-session only: may only have live ZipEntry[] with leaves from write
+      return super.getMerkleRootAsync(options);
+    }
+
+    try {
+      for (const entry of contentEntries) {
+        if (entry.merkleLeafV1) {
+          continue;
+        }
+        await this.getZipDecompressNode().testEntry(entry, { skipHashCheck: false });
+      }
+    } catch (err) {
+      console.error('[ZipkitNode.getMerkleRootAsync] stream hash failed:', err);
+      return null;
+    }
+
+    if (!contentEntries.every((e) => !!e.merkleLeafV1)) {
+      return null;
+    }
+
+    return computeMerkleRootV1FromLeaves(
+      contentEntries.map((e) => ({
+        path: e.filename || '',
+        merkleLeafV1: e.merkleLeafV1 as string,
+      }))
+    );
+  }
+
   // ============================================================================
   // File Loading Methods
   // ============================================================================
@@ -650,11 +729,10 @@ export default class ZipkitNode extends Zipkit {
     }
 
     // For AES encryption, pre-configure the entry so the initial local header
-    // includes the 0x9901 extra field and method 99. The actual compression
-    // method is preserved in realCmpMethod for the AES extra field.
-    // Default password encryption is WinZip AES-256 (matches compressData).
+    // matches the chosen scheme (WinZip method 99 + 0x9901, or NeoEncrypt + 0x024E).
+    // Default password encryption is NeoEncrypt (matches NeoZip product AES-256).
     const encMethod = options?.password
-      ? (options.encryptionMethod || 'aes256')
+      ? (options.encryptionMethod || 'neo-aes256')
       : undefined;
     const isAesRequested = encMethod === 'aes256';
     const isNeoRequested = encMethod === 'neo-aes256';