neozipkit 1.0.2 → 1.5.0

package/src/core/index.ts

@@ -10,6 +10,7 @@ export * from './ZipEntry';
 export { ZipCompress } from './ZipCompress';
 export type { CompressOptions, CreateZipOptions } from './ZipCompress';
 export type { DecompressionResult, DecompressionOptions } from './ZipDecompress';
+export { inflateZipPayload } from './inflateZipPayload';
 export { ZipCopy } from './ZipCopy';
 export type {
   CopyOptions,
@@ -24,6 +25,9 @@ export { default as HashCalculator, HashCalculator as HashCalculatorClass } from
 export * from './components/Util';
 export * from './components/Support';
 export { ProgressTracker } from './components/ProgressTracker';
+export * from './merkle/MerkleRoot';
+export * from './zip64/Zip64';
+export * from './origin/OriginExtra';
 
 // Encryption functionality
 export { EncryptionManager } from './encryption/Manager';
@@ -33,6 +37,19 @@ export type { EncryptionMethod, EncryptionOptions, EncryptionResult, DecryptionR
 // Types and constants
 export * from '../types';
 export * from './constants/Headers';
+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,
+  asciiPathEqualsIgnoreCase,
+  isMetaInfPath,
+  isReservedMetaPath,
+  findReservedMetaEntry,
+} from './constants/MetaPaths';
 export * from './constants/Errors';
 export * from './version';
 

package/src/core/inflateZipPayload.ts

@@ -0,0 +1,27 @@
+/**
+ * Inflate one ZIP member payload (store, deflate, zstd) from an in-memory buffer.
+ * Browser bundles alias ZstdNode to the CompressionStream codec.
+ */
+
+import pako from 'pako';
+import { decompress } from '../node/ZstdNode';
+
+export async function inflateZipPayload(
+  method: number,
+  compressed: Uint8Array | ArrayBuffer,
+): Promise<Uint8Array> {
+  const bytes =
+    compressed instanceof ArrayBuffer ? new Uint8Array(compressed) : compressed;
+  if (method === 0) {
+    return bytes.slice();
+  }
+  if (method === 8) {
+    const out = pako.inflateRaw(bytes);
+    return out instanceof Uint8Array ? out : new Uint8Array(out);
+  }
+  if (method === 93) {
+    const out = await decompress(bytes);
+    return new Uint8Array(out.buffer, out.byteOffset, out.byteLength);
+  }
+  throw new Error(`unsupported compression method ${method}`);
+}

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/origin/OriginExtra.ts

@@ -0,0 +1,209 @@
+// ======================================
+//	OriginExtra.ts — NeoZip Extra Field 0x014F (original locator)
+//  Copyright (c) 2026 NeoWare, Inc. All rights reserved.
+// ======================================
+// APPNOTE §7.1.1 / ZipWiki §6.7 — v1 TLV (URI, CRC-32, size, mtime, SHA-256).
+// The kit stores opaque caller extras on ZipEntry.additionalExtra; these helpers
+// build and parse the 0x014F wire form.
+
+import { HDR_ID } from '../constants/Headers';
+import { crc32, sha256 } from '../encryption/ZipCrypto';
+
+/** Payload version byte. Stays 0x01 until first release. */
+export const ORIGIN_EXTRA_VERSION = 0x01;
+
+/** Soft cap on URI byte length (well under uint16 extra size). */
+export const ORIGIN_URI_MAX_BYTES = 2048;
+
+/** Registered v1 TLV tags. Unknown tags are skipped (forward compatible). */
+export const ORIGIN_TAG = {
+  URI: 0x01,
+  CRC32: 0x02,
+  SIZE: 0x03,
+  MTIME: 0x04,
+  SHA256: 0x05,
+} as const;
+
+export type OriginLocator = {
+  /** Absolute RFC 3986 URI (`https:` / `http:` / `file:`). */
+  uri?: string;
+  /** ZIP/IEEE CRC-32 of original uncompressed bytes. */
+  crc32?: number;
+  /** Original uncompressed byte length. */
+  size?: number;
+  /** Original modification time: Unix seconds (UTC, signed). */
+  mtime?: number;
+  /** SHA-256 of original uncompressed bytes (32 bytes or hex). */
+  sha256?: Buffer | string;
+};
+
+function originSha256Bytes(value: Buffer | string): Buffer {
+  const buf = typeof value === 'string' ? Buffer.from(value, 'hex') : value;
+  if (buf.length !== 32) {
+    throw new Error('0x014F sha256 must be 32 bytes');
+  }
+  return buf;
+}
+
+function tlv(tag: number, value: Buffer): Buffer {
+  const rec = Buffer.alloc(3 + value.length);
+  rec.writeUInt8(tag, 0);
+  rec.writeUInt16LE(value.length, 1);
+  value.copy(rec, 3);
+  return rec;
+}
+
+function assertInteger(name: string, value: number): void {
+  if (!Number.isFinite(value) || !Number.isInteger(value)) {
+    throw new Error(`0x014F ${name} must be an integer`);
+  }
+}
+
+export function originLocatorPresent(
+  loc: OriginLocator | null | undefined
+): loc is OriginLocator {
+  if (!loc) return false;
+  return (
+    (typeof loc.uri === 'string' && loc.uri.length > 0) ||
+    loc.crc32 !== undefined ||
+    loc.size !== undefined ||
+    loc.mtime !== undefined ||
+    loc.sha256 !== undefined
+  );
+}
+
+/** ZIP/IEEE CRC-32 of uncompressed original bytes. */
+export function originCrc32Of(buf: Buffer): number {
+  return crc32(buf) >>> 0;
+}
+
+/** SHA-256 of uncompressed original bytes (32-byte Buffer). */
+export function originSha256Of(buf: Buffer): Buffer {
+  return Buffer.from(sha256(buf), 'hex');
+}
+
+/** Truncate a Date to Unix seconds (UTC). */
+export function unixTimeSeconds(date: Date): number {
+  return Math.floor(date.getTime() / 1000);
+}
+
+/**
+ * Build Extra Field 0x014F (v1 TLV). Throws if no attribute is present,
+ * if URI is empty when provided, or if URI exceeds max bytes.
+ */
+export function makeOriginExtra(loc: OriginLocator): Buffer {
+  const records: Buffer[] = [];
+
+  const uri = loc.uri?.trim();
+  if (uri !== undefined && uri.length === 0) {
+    throw new Error('0x014F URI must be non-empty when present');
+  }
+  if (uri) {
+    const uriBuf = Buffer.from(uri, 'utf8');
+    if (uriBuf.length > ORIGIN_URI_MAX_BYTES) {
+      throw new Error(
+        `0x014F URI exceeds ${ORIGIN_URI_MAX_BYTES} bytes (${uriBuf.length})`
+      );
+    }
+    records.push(tlv(ORIGIN_TAG.URI, uriBuf));
+  }
+
+  if (loc.crc32 !== undefined) {
+    assertInteger('crc32', loc.crc32);
+    const b = Buffer.alloc(4);
+    b.writeUInt32LE(loc.crc32 >>> 0, 0);
+    records.push(tlv(ORIGIN_TAG.CRC32, b));
+  }
+
+  if (loc.size !== undefined) {
+    assertInteger('size', loc.size);
+    if (loc.size < 0) {
+      throw new Error('0x014F size must be >= 0');
+    }
+    const b = Buffer.alloc(8);
+    b.writeBigUInt64LE(BigInt(loc.size), 0);
+    records.push(tlv(ORIGIN_TAG.SIZE, b));
+  }
+
+  if (loc.mtime !== undefined) {
+    assertInteger('mtime', loc.mtime);
+    const b = Buffer.alloc(8);
+    b.writeBigInt64LE(BigInt(loc.mtime), 0);
+    records.push(tlv(ORIGIN_TAG.MTIME, b));
+  }
+
+  if (loc.sha256 !== undefined) {
+    records.push(tlv(ORIGIN_TAG.SHA256, originSha256Bytes(loc.sha256)));
+  }
+
+  if (records.length === 0) {
+    throw new Error('0x014F requires at least one attribute');
+  }
+
+  const dataSize = 1 + records.reduce((n, r) => n + r.length, 0);
+  const extra = Buffer.alloc(4 + dataSize);
+  extra.writeUInt16LE(HDR_ID.ORIGIN, 0);
+  extra.writeUInt16LE(dataSize, 2);
+  extra.writeUInt8(ORIGIN_EXTRA_VERSION, 4);
+  let off = 5;
+  for (const rec of records) {
+    rec.copy(extra, off);
+    off += rec.length;
+  }
+  return extra;
+}
+
+function parseOriginTlv(data: Buffer): OriginLocator | null {
+  const loc: OriginLocator = {};
+  let i = 0;
+  while (i + 3 <= data.length) {
+    const tag = data.readUInt8(i);
+    const len = data.readUInt16LE(i + 1);
+    i += 3;
+    if (i + len > data.length) break;
+    const value = data.subarray(i, i + len);
+    i += len;
+    if (tag === ORIGIN_TAG.URI && len > 0) {
+      const u = value.toString('utf8');
+      if (u.length > 0) loc.uri = u;
+    } else if (tag === ORIGIN_TAG.CRC32 && len === 4) {
+      loc.crc32 = value.readUInt32LE(0) >>> 0;
+    } else if (tag === ORIGIN_TAG.SIZE && len === 8) {
+      loc.size = Number(value.readBigUInt64LE(0));
+    } else if (tag === ORIGIN_TAG.MTIME && len === 8) {
+      loc.mtime = Number(value.readBigInt64LE(0));
+    } else if (tag === ORIGIN_TAG.SHA256 && len === 32) {
+      loc.sha256 = Buffer.from(value);
+    }
+  }
+  return originLocatorPresent(loc) ? loc : null;
+}
+
+/** Walk a ZIP Extra Field blob for NeoZip 0x014F (v1 TLV). */
+export function parseOriginFromExtra(extra: Buffer | null | undefined): OriginLocator | null {
+  if (!extra || extra.length < 4) return null;
+  let i = 0;
+  while (i + 4 <= extra.length) {
+    const id = extra.readUInt16LE(i);
+    const size = extra.readUInt16LE(i + 2);
+    i += 4;
+    if (i + size > extra.length) break;
+    if (id === HDR_ID.ORIGIN && size >= 1) {
+      const version = extra.readUInt8(i);
+      const payload = extra.subarray(i + 1, i + size);
+      if (version === ORIGIN_EXTRA_VERSION) {
+        const loc = parseOriginTlv(payload);
+        if (loc) return loc;
+      }
+    }
+    i += size;
+  }
+  return null;
+}
+
+/** Read origin locator from a ZipEntry's preserved caller extras. */
+export function parseOriginFromEntry(entry: {
+  additionalExtra?: Buffer | null;
+}): OriginLocator | null {
+  return parseOriginFromExtra(entry.additionalExtra ?? null);
+}

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.5.0', // packageJson.version
   date: releaseDate
 };