neozipkit 1.0.5 → 1.5.0

package/src/core/Zipkit.ts

@@ -25,7 +25,7 @@ import {
   CENTRAL_END, 
   CENTRAL_DIR, 
   ZIP64_CENTRAL_END, 
-  ZIP64_CENTRAL_DIR ,
+  ZIP64_CENTRAL_DIR,
   GP_FLAG,
   TIMESTAMP_SUBMITTED,
   TIMESTAMP_METADATA,
@@ -35,6 +35,14 @@ import {
   CENTRAL_DIRECTORY_END,
   HDR_ID
 } from './constants/Headers';
+import {
+  buildEndRecords,
+  classicEocdNeedsZip64,
+  parseZip64Eocd,
+  parseZip64Locator,
+  ZIP64_EOCD_RECORD_SIZE,
+  ZIP64_LOCATOR_SIZE,
+} from './zip64/Zip64';
 import {
   findReservedMetaEntry,
   isMetaInfPath,
@@ -605,17 +613,30 @@ export default class Zipkit {
     if (eocdBuffer.readUInt32LE(0) === CENTRAL_END.SIGNATURE) {
       this.centralDirSize = eocdBuffer.readUInt32LE(CENTRAL_END.CENTRAL_DIR_SIZE);
       this.centralDirOffset = eocdBuffer.readUInt32LE(CENTRAL_END.CENTRAL_DIR_OFFSET);
-
-      if (this.centralDirOffset === 0xFFFFFFFF) {
-        // ZIP64: locate locator (20 bytes before EOCD) and then ZIP64 EOCD (56 bytes)
-        const locatorOffset = eocdOffset - 20;
-        const locatorBuffer = buffer.subarray(locatorOffset, locatorOffset + 20);
-        if (locatorBuffer.readUInt32LE(0) === ZIP64_CENTRAL_END.SIGNATURE) {
-          const zip64Offset = Number(locatorBuffer.readBigUInt64LE(8));
-          const zip64Buffer = buffer.subarray(zip64Offset, zip64Offset + 56);
-          this.centralDirSize = Number(zip64Buffer.readBigUInt64LE(ZIP64_CENTRAL_DIR.CENTRAL_DIR_SIZE));
-          this.centralDirOffset = Number(zip64Buffer.readBigUInt64LE(ZIP64_CENTRAL_DIR.CENTRAL_DIR_OFFSET));
+      const volEntries = eocdBuffer.readUInt16LE(CENTRAL_END.VOL_ENTRIES);
+      const totalEntries = eocdBuffer.readUInt16LE(CENTRAL_END.TOTAL_ENTRIES);
+
+      if (
+        classicEocdNeedsZip64({
+          volEntries,
+          totalEntries,
+          centralDirSize: this.centralDirSize,
+          centralDirOffset: this.centralDirOffset,
+        })
+      ) {
+        const locatorOffset = eocdOffset - ZIP64_LOCATOR_SIZE;
+        if (locatorOffset < 0) {
+          throw new Error(Errors.INVALID_FORMAT);
         }
+        const locatorBuffer = buffer.subarray(locatorOffset, locatorOffset + ZIP64_LOCATOR_SIZE);
+        const zip64Offset = parseZip64Locator(locatorBuffer);
+        const zip64Buffer = buffer.subarray(
+          zip64Offset,
+          zip64Offset + ZIP64_EOCD_RECORD_SIZE
+        );
+        const z64 = parseZip64Eocd(zip64Buffer);
+        this.centralDirSize = z64.centralDirSize;
+        this.centralDirOffset = z64.centralDirOffset;
       }
     } else {
       throw new Error(Errors.INVALID_FORMAT);
@@ -691,17 +712,14 @@ export default class Zipkit {
    * Note: totalEntries must be passed as parameter since zipEntries[] in Zipkit is the cache
    */
   private centralEndHdrMethod(centralDirSize: number, centralDirOffset: number, totalEntries: number): Buffer {
-    const ceBuf = Buffer.alloc(CENTRAL_END.SIZE);
-    ceBuf.writeUInt32LE(CENTRAL_END.SIGNATURE, 0);
-    ceBuf.writeUInt16LE(0, 4); // Number of this disk
-    ceBuf.writeUInt16LE(0, 6); // Number of the disk with the start of the central directory
-    ceBuf.writeUInt16LE(totalEntries, 8); // Total number of entries
-    ceBuf.writeUInt16LE(totalEntries, 10); // Total number of entries on this disk
-    ceBuf.writeUInt32LE(centralDirSize, 12); // Size of central directory
-    ceBuf.writeUInt32LE(centralDirOffset, 16); // Offset of start of central directory
-    ceBuf.writeUInt16LE(0, 20); // ZIP file comment length
-    
-    return ceBuf;
+    // Buffer path: allow entry-count Zip64; refuse size/offset Zip64 (multi-GiB in memory).
+    return buildEndRecords({
+      totalEntries,
+      centralDirSize,
+      centralDirOffset,
+      zip64EocdOffset: centralDirOffset + centralDirSize,
+      allowSizeOffsetZip64: false,
+    });
   }
 
   /**

package/src/core/constants/Headers.ts

@@ -187,6 +187,7 @@ export const HDR_ID = {
   IBM1:            0x0065,    // IBM S/390 (Z390) - Attribute
   IBM2:            0x0066,    // IBM S/390 (Z390) - Attribute
   SHA256:          0x014E,    // NeoZip Extra Field: 32-byte SHA-256 of uncompressed payload (APPNOTE §5)
+  ORIGIN:          0x014F,    // ZipWiki origin locator (URI, size, mtime, CRC-32 or SHA-256)
   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/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,
@@ -25,6 +26,8 @@ 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';

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/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.5', // packageJson.version
+  number: '1.5.0', // packageJson.version
   date: releaseDate
 };