neozipkit 0.8.0 → 1.0.5

package/src/core/components/HashCalculator.ts

@@ -45,6 +45,8 @@ export class HashCalculator {
   // Incremental hash calculation state (from StreamHashCalculator)
   private crc32State: number = ~0;
   private sha256Hash: crypto.Hash | null = null;
+  /** Domain-separated leaf hasher (APPNOTE §6.3): SHA-256(0x00 ‖ payload). */
+  private merkleLeafHash: crypto.Hash | null = null;
   private useSHA256: boolean = false;
 
   // Hash accumulation state (from HashAccumulator)
@@ -52,13 +54,15 @@ export class HashCalculator {
   private xorResult: Buffer = Buffer.alloc(32, 0);
   private enableAccumulation: boolean = false;
 
-  // Merkle tree state (from MerkleTree)
+  // Merkle tree state (from MerkleTree) — generic digest folding; archive roots use merkle/MerkleRoot.ts
   private merkleLeaves: Buffer[] = [];
   private merkleLayers: Buffer[][] = [];
   private merkleOptions: MerkleTreeOptions = {
     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
   };
 
@@ -77,6 +81,8 @@ export class HashCalculator {
 
     if (this.useSHA256) {
       this.sha256Hash = crypto.createHash('sha256');
+      this.merkleLeafHash = crypto.createHash('sha256');
+      this.merkleLeafHash.update(Buffer.from([0x00]));
     }
   }
 
@@ -95,10 +101,13 @@ export class HashCalculator {
       this.crc32State = crc32update(this.crc32State, chunk[i]);
     }
     
-    // Update SHA-256 incrementally
+    // Update SHA-256 and v1 Merkle leaf hash incrementally
     if (this.sha256Hash) {
       this.sha256Hash.update(chunk);
     }
+    if (this.merkleLeafHash) {
+      this.merkleLeafHash.update(chunk);
+    }
   }
 
   /**
@@ -110,7 +119,7 @@ export class HashCalculator {
   }
 
   /**
-   * 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(): string | null {
@@ -120,13 +129,55 @@ export class HashCalculator {
     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(): string | null {
+    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: {
+      crc: number;
+      sha256: string | null;
+      merkleLeafV1?: string | null;
+    },
+    options: { setCrc?: boolean; setSha256?: boolean }
+  ): void {
+    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(): void {
     this.crc32State = ~0;
-    if (this.sha256Hash) {
+    if (this.useSHA256) {
       this.sha256Hash = crypto.createHash('sha256');
+      this.merkleLeafHash = crypto.createHash('sha256');
+      this.merkleLeafHash.update(Buffer.from([0x00]));
     }
   }
 
@@ -264,6 +315,7 @@ export class HashCalculator {
     if (this.merkleOptions.sortPairs && Buffer.compare(left, right) > 0) {
       [left, right] = [right, left];
     }
+    // Generic accumulator tree (not APPNOTE archive root — see merkle/MerkleRoot.ts)
     return this.hash(Buffer.concat([left, right]));
   }
 

package/src/core/components/Util.ts

@@ -6,7 +6,19 @@
 
 import Support from "./Support";
 import Errors from "../constants/Errors";
-import { TIMESTAMP_SUBMITTED, TIMESTAMP_METADATA, TOKENIZED_METADATA } from "../constants/Headers";
+import {
+  isMetaInfPath,
+  findReservedMetaEntry,
+  isReservedMetaPath,
+  asciiPathEqualsIgnoreCase,
+} from "../constants/MetaPaths";
+
+export {
+  findReservedMetaEntry,
+  isReservedMetaPath,
+  isMetaInfPath,
+  asciiPathEqualsIgnoreCase,
+} from "../constants/MetaPaths";
 
 export const DATATYPE = {
   STRING: "string",
@@ -80,12 +92,9 @@ export function getTypeOf(input: string|Buffer|Blob|Array<any>|ArrayBuffer|Uint8
 };
 
 /**
- * Check if a filename is a metadata file
- * @param filename The filename to check
- * @returns True if the file is a metadata file (META-INF)
+ * Check if a filename is NeoZip metadata (any META-INF/** path).
+ * Case-insensitive on the META-INF/ prefix (NEOZIP_APPNOTE.md §2.3 / §6.2).
  */
 export const isMetadataFile = (filename: string): boolean => {
-  return filename === TIMESTAMP_SUBMITTED || 
-         filename === TIMESTAMP_METADATA || 
-         filename === TOKENIZED_METADATA;
+  return isMetaInfPath(filename);
 };

package/src/core/constants/Headers.ts

@@ -11,9 +11,19 @@ export const ZIP64_CENTRAL_DIRECTORY_LOCATOR = 'PK\x06\x07';
 export const ZIP64_CENTRAL_DIRECTORY_END = 'PK\x06\x06';
 export const DATA_DESCRIPTOR = 'PK\x07\x08';
 
-export const TIMESTAMP_SUBMITTED = 'META-INF/TS-SUBMIT.OTS';
-export const TIMESTAMP_METADATA = 'META-INF/TIMESTAMP.OTS';
-export const TOKENIZED_METADATA = 'META-INF/NZIP.TOKEN';
+// Reserved META-INF paths — see constants/MetaPaths.ts and NEOZIP_APPNOTE.md §2
+export {
+  META_TOKEN_NZIP,
+  META_TOKEN_NZIP_LEGACY,
+  META_TS_SUBMIT_NZIP,
+  META_TIMESTAMP_NZIP,
+  META_TS_SUBMIT_OTS,
+  META_TIMESTAMP_OTS,
+  META_MANIFEST_JSON,
+  TIMESTAMP_SUBMITTED,
+  TIMESTAMP_METADATA,
+  TOKENIZED_METADATA,
+} from './MetaPaths';
 
 // Local file header
 export const LOCAL_HDR = {
@@ -176,7 +186,7 @@ export const HDR_ID = {
   x509PKCS7RL:     0x0019,    // X.509 Certificate Revocation List (PKCS#7)
   IBM1:            0x0065,    // IBM S/390 (Z390) - Attribute
   IBM2:            0x0066,    // IBM S/390 (Z390) - Attribute
-  SHA256:          0x014E,    // SHA256 "N\01" with 64 bytes (256 bit) of SHA256 hash data
+  SHA256:          0x014E,    // NeoZip Extra Field: 32-byte SHA-256 of uncompressed payload (APPNOTE §5)
   NEO_CRYPTO:      0x024E,    // NeoEncrypt metadata (see docs/NEO_CRYPTO_FORMAT.md); LE on wire: 4E 02
   POSZIP:          0x4690,    // POSZIP 4690
   UNV_TIME:        0x5455,    // Universal Time (UT) (32-bit) 5 data bytes

package/src/core/constants/MetaPaths.ts

@@ -0,0 +1,86 @@
+/**
+ * NeoZip reserved META-INF paths and ASCII case-insensitive discovery.
+ * Matches NEOZIP_APPNOTE.md §2.3: writers emit canonical spellings; readers fold case.
+ */
+
+/** Canonical writers MUST emit these spellings. */
+export const META_TOKEN_NZIP = 'META-INF/TOKEN.NZIP';
+export const META_TOKEN_NZIP_LEGACY = 'META-INF/NZIP.TOKEN';
+export const META_TS_SUBMIT_NZIP = 'META-INF/TS-SUBMIT.NZIP';
+export const META_TIMESTAMP_NZIP = 'META-INF/TIMESTAMP.NZIP';
+export const META_TS_SUBMIT_OTS = 'META-INF/TS-SUBMIT.OTS';
+export const META_TIMESTAMP_OTS = 'META-INF/TIMESTAMP.OTS';
+export const META_MANIFEST_JSON = 'META-INF/manifest.json';
+
+/** @deprecated Prefer META_TS_SUBMIT_OTS — kept for existing imports. */
+export const TIMESTAMP_SUBMITTED = META_TS_SUBMIT_OTS;
+/** @deprecated Prefer META_TIMESTAMP_OTS — kept for existing imports. */
+export const TIMESTAMP_METADATA = META_TIMESTAMP_OTS;
+/** @deprecated Prefer META_TOKEN_NZIP — kept for existing imports (canonical TOKEN.NZIP). */
+export const TOKENIZED_METADATA = META_TOKEN_NZIP;
+
+const 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,
+] as const;
+
+export type ZipEntryLikeFilename = { filename?: string };
+
+/** ASCII case-insensitive path compare (APPNOTE §2.3). */
+export function asciiPathEqualsIgnoreCase(a: string, b: string): boolean {
+  if (a.length !== b.length) {
+    // Still allow length mismatch only via toLowerCase for UTF-8 safety on ASCII paths
+  }
+  return a.toLowerCase() === b.toLowerCase();
+}
+
+/** True when path is under META-INF/ (ASCII case-insensitive). */
+export function isMetaInfPath(filename: string): boolean {
+  return filename.toLowerCase().startsWith('meta-inf/');
+}
+
+/** True when filename is a reserved NeoZip meta path (any casing). */
+export function isReservedMetaPath(filename: string): boolean {
+  const lower = filename.toLowerCase();
+  return RESERVED_CANONICAL.some((c) => c.toLowerCase() === lower);
+}
+
+/**
+ * True for any META-INF/** entry (integrity merkle leaves exclude these per APPNOTE §6.2).
+ */
+export function isMetadataFile(filename: string): boolean {
+  return isMetaInfPath(filename);
+}
+
+/**
+ * Find a reserved meta entry among ZIP directory entries.
+ * Prefers an exact canonical match, then ASCII case-insensitive match.
+ * When multiple preferred names are given, earlier names win.
+ */
+export function findReservedMetaEntry<T extends ZipEntryLikeFilename>(
+  entries: T[],
+  preferredCanonicalNames: string | readonly string[]
+): T | null {
+  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;
+}