neozipkit 1.0.2 → 1.5.0

package/src/node/ZipCopyNode.ts

@@ -10,7 +10,11 @@
 import * as fs from 'fs';
 import ZipEntry from '../core/ZipEntry';
 import ZipkitNode from './ZipkitNode';
-import { LOCAL_HDR, CENTRAL_END, GP_FLAG } from '../core/constants/Headers';
+import { LOCAL_HDR, GP_FLAG } from '../core/constants/Headers';
+import {
+  buildEndRecords,
+  dataDescriptorByteLength,
+} from '../core/zip64/Zip64';
 
 /**
  * Options for copying ZIP files
@@ -159,9 +163,12 @@ export class ZipCopyNode {
     const localHeaderSize = this.calculateLocalHeaderSize(sourceFd, entry);
     
     // Determine total entry size
-    // For data descriptor entries, add 16 bytes for the data descriptor
+    // For data descriptor entries, add Zip64 (24) or classic (16) descriptor bytes
     const hasDataDescriptor = (entry.bitFlags & GP_FLAG.DATA_DESC) !== 0;
-    const totalEntrySize = localHeaderSize + entry.compressedSize + (hasDataDescriptor ? 16 : 0);
+    const descLen = hasDataDescriptor
+      ? dataDescriptorByteLength(entry.usesZip64Extra)
+      : 0;
+    const totalEntrySize = localHeaderSize + entry.compressedSize + descLen;
 
     // Read the entire entry (local header + compressed data + data descriptor if present) from source
     const entryBuffer = Buffer.alloc(totalEntrySize);
@@ -248,6 +255,10 @@ export class ZipCopyNode {
     cloned.uid = entry.uid;
     cloned.gid = entry.gid;
     cloned.sha256 = entry.sha256;
+    cloned.emitUnicodePath = entry.emitUnicodePath;
+    if (entry.additionalExtra) {
+      cloned.additionalExtra = Buffer.from(entry.additionalExtra);
+    }
 
     // Copy symlink data
     cloned.isSymlink = entry.isSymlink;
@@ -258,6 +269,14 @@ export class ZipCopyNode {
     cloned.originalEntry = entry.originalEntry;
     cloned.inode = entry.inode;
 
+    cloned.usesZip64Extra = entry.usesZip64Extra;
+    cloned.aesVersion = entry.aesVersion;
+    cloned.aesStrength = entry.aesStrength;
+    cloned.realCmpMethod = entry.realCmpMethod;
+    cloned.neoCryptoPayloadVersion = entry.neoCryptoPayloadVersion;
+    cloned.neoCryptoAlgorithm = entry.neoCryptoAlgorithm;
+    cloned.neoCryptoFlags = entry.neoCryptoFlags;
+
     return cloned;
   }
 
@@ -280,33 +299,16 @@ export class ZipCopyNode {
     const centralDirEndOffset = fs.fstatSync(destFd).size;
     const centralDirSize = centralDirEndOffset - centralDirStartOffset;
 
-    const commentBytes = Buffer.from(zipComment, 'utf8');
-    const commentLength = Math.min(commentBytes.length, 0xFFFF);
-
-    const eocdBuffer = Buffer.alloc(22 + commentLength);
-    let pos = 0;
-
-    eocdBuffer.writeUInt32LE(CENTRAL_END.SIGNATURE, pos);
-    pos += 4;
-    eocdBuffer.writeUInt16LE(0, pos);
-    pos += 2;
-    eocdBuffer.writeUInt16LE(0, pos);
-    pos += 2;
-    eocdBuffer.writeUInt16LE(entries.length, pos);
-    pos += 2;
-    eocdBuffer.writeUInt16LE(entries.length, pos);
-    pos += 2;
-    eocdBuffer.writeUInt32LE(centralDirSize, pos);
-    pos += 4;
-    eocdBuffer.writeUInt32LE(centralDirStartOffset, pos);
-    pos += 4;
-    eocdBuffer.writeUInt16LE(commentLength, pos);
-    pos += 2;
-    if (commentLength > 0) {
-      commentBytes.copy(eocdBuffer, pos, 0, commentLength);
-    }
+    const endRecords = buildEndRecords({
+      totalEntries: entries.length,
+      centralDirSize,
+      centralDirOffset: centralDirStartOffset,
+      zip64EocdOffset: centralDirStartOffset + centralDirSize,
+      archiveComment: zipComment,
+      allowSizeOffsetZip64: true,
+    });
 
-    fs.writeSync(destFd, eocdBuffer, 0, eocdBuffer.length);
+    fs.writeSync(destFd, endRecords, 0, endRecords.length);
 
     return { centralDirOffset: centralDirStartOffset, centralDirSize };
   }

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);
@@ -588,7 +592,8 @@ export class ZipDecompressNode {
     const decompressedStream = this.decompressStream(compressedStream, entry.cmpMethod, undefined, entry);
     
     // Process and validate chunks - one block at a time
-    const hashCalc = new HashCalculator({ useSHA256: !!entry.sha256 });
+    // Always hash the v1 Merkle leaf so getMerkleRootAsync works for CRC-only archives.
+    const hashCalc = new HashCalculator({ useSHA256: true });
     let totalBytes = 0;
     
     try {
@@ -607,6 +612,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);
@@ -616,16 +623,22 @@ export class ZipDecompressNode {
           return { verifiedHash: calculatedHash };
         } else {
           const calculatedCRC = hashCalc.finalizeCRC32();
+          const leaf = hashCalc.finalizeMerkleLeafV1();
+          if (leaf) entry.merkleLeafV1 = leaf;
           this.log(`CRC-32 comparison: calculated=${calculatedCRC}, stored=${entry.crc}`);
           if (calculatedCRC !== entry.crc) {
             throw new Error(Errors.INVALID_CRC);
           }
           this.log(`CRC-32 comparison: calculated=${calculatedCRC}, stored=${entry.crc}`);
-          // No hash to return for CRC-32 only entries
           return { verifiedHash: undefined };
         }
       } else {
-        // Hash check skipped - return undefined
+        const leaf = hashCalc.finalizeMerkleLeafV1();
+        if (leaf) entry.merkleLeafV1 = leaf;
+        if (entry.sha256 && hashCalc) {
+          const calculatedHash = hashCalc.finalizeSHA256();
+          return { verifiedHash: calculatedHash || undefined };
+        }
         return { verifiedHash: undefined };
       }
     } catch (error) {

package/src/node/ZipkitNode.ts

@@ -11,22 +11,40 @@ import { ZipDecompressNode } from './ZipDecompressNode';
 import { 
   CENTRAL_END, 
   CENTRAL_DIR, 
-  ZIP64_CENTRAL_END, 
-  ZIP64_CENTRAL_DIR,
   LOCAL_HDR,
   GP_FLAG,
   CMP_METHOD,
-  ENCRYPT_HDR_SIZE
+  ENCRYPT_HDR_SIZE,
+  HDR_ID,
 } from '../core/constants/Headers';
+import {
+  buildEndRecords,
+  classicEocdNeedsZip64,
+  exceedsU32,
+  parseZip64Eocd,
+  parseZip64Locator,
+  writeU64,
+  ZIP64_EOCD_RECORD_SIZE,
+  ZIP64_LOCATOR_SIZE,
+  ZIP64_U32,
+} from '../core/zip64/Zip64';
 import { NEO_CRYPTO_ALGORITHM_AES256_V1 } from '../core/encryption/NeoCrypto';
 import { AesCrypto } from '../core/encryption/AesCrypto';
 import {
   detectLegacyWasmZstd,
   type LegacyZstdDetectResult,
 } from './LegacyZstd';
+import { writeZipFileSync, type ZipBufferMember, type BuildZipBufferOptions } from './buildZipBuffer';
+export type { ZipBufferMember };
 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 +129,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
   // ============================================================================
@@ -638,6 +729,10 @@ export default class ZipkitNode extends Zipkit {
       onHashCalculated?: (entry: ZipEntry, hash: Buffer) => void;
     }
   ): Promise<void> {
+    if (options?.forceZip64) {
+      entry.forceZip64 = true;
+    }
+
     // Set compression method based on options
     const level = options?.level ?? 6;
     let realCmpMethod: number;
@@ -650,11 +745,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';
@@ -781,9 +875,55 @@ export default class ZipkitNode extends Zipkit {
       throw new Error(`Compressed size not set for entry: ${entry.filename}`);
     }
 
-    const sizeBuffer = Buffer.alloc(4);
-    sizeBuffer.writeUInt32LE(entry.compressedSize, 0);
-    fs.writeSync(writer.outputFd, sizeBuffer, 0, 4, entry.localHdrOffset + 18);
+    const classicCmp = entry.localHdrOffset + LOCAL_HDR.CMP_SIZE;
+    const classicUncmp = entry.localHdrOffset + LOCAL_HDR.UNCMP_SIZE;
+    const useZip64Sizes =
+      entry.forceZip64 ||
+      exceedsU32(entry.uncompressedSize) ||
+      exceedsU32(entry.compressedSize);
+
+    if (useZip64Sizes) {
+      // Classic fields stay at 0xFFFFFFFF; update u64 sizes inside local extra 0x0001
+      const sentinel = Buffer.alloc(4);
+      sentinel.writeUInt32LE(ZIP64_U32, 0);
+      fs.writeSync(writer.outputFd, sentinel, 0, 4, classicCmp);
+      fs.writeSync(writer.outputFd, sentinel, 0, 4, classicUncmp);
+
+      const fnameLenBuf = Buffer.alloc(2);
+      fs.readSync(writer.outputFd, fnameLenBuf, 0, 2, entry.localHdrOffset + LOCAL_HDR.FNAME_LEN);
+      const fnameLen = fnameLenBuf.readUInt16LE(0);
+      const extraLenBuf = Buffer.alloc(2);
+      fs.readSync(writer.outputFd, extraLenBuf, 0, 2, entry.localHdrOffset + LOCAL_HDR.EXTRA_LEN);
+      const extraLen = extraLenBuf.readUInt16LE(0);
+      const extraStart = entry.localHdrOffset + LOCAL_HDR.SIZE + fnameLen;
+      const extraBuf = Buffer.alloc(extraLen);
+      if (extraLen > 0) {
+        fs.readSync(writer.outputFd, extraBuf, 0, extraLen, extraStart);
+      }
+      let patched = false;
+      for (let i = 0; i + 4 <= extraBuf.length; ) {
+        const id = extraBuf.readUInt16LE(i);
+        const len = extraBuf.readUInt16LE(i + 2);
+        if (id === HDR_ID.ZIP64 && len >= 16) {
+          // Local Zip64 always has uncompressed (8) then compressed (8)
+          writeU64(extraBuf, i + 4, entry.uncompressedSize);
+          writeU64(extraBuf, i + 12, entry.compressedSize);
+          fs.writeSync(writer.outputFd, extraBuf, i + 4, 16, extraStart + i + 4);
+          patched = true;
+          break;
+        }
+        i += 4 + len;
+      }
+      if (!patched) {
+        throw new Error(
+          `Zip64 local extra (0x0001) missing for large entry: ${entry.filename}`
+        );
+      }
+    } else {
+      const sizeBuffer = Buffer.alloc(4);
+      sizeBuffer.writeUInt32LE(entry.compressedSize, 0);
+      fs.writeSync(writer.outputFd, sizeBuffer, 0, 4, classicCmp);
+    }
 
     if (entry.crc !== undefined) {
       const crcBuffer = Buffer.alloc(4);
@@ -860,6 +1000,7 @@ export default class ZipkitNode extends Zipkit {
    * @param centralDirSize - Size of central directory in bytes
    * @param centralDirOffset - Offset to start of central directory
    * @param archiveComment - Optional archive comment (max 65535 bytes)
+   * @param options - Optional Zip64 force and related EOCD flags
    * @returns Promise that resolves when EOCD is written
    */
   async writeEndOfCentralDirectory(
@@ -867,53 +1008,20 @@ export default class ZipkitNode extends Zipkit {
     totalEntries: number,
     centralDirSize: number,
     centralDirOffset: number,
-    archiveComment?: string
+    archiveComment?: string,
+    options?: { forceZip64?: boolean }
   ): Promise<void> {
-    const comment = archiveComment || '';
-    const commentBytes = Buffer.from(comment, 'utf8');
-    const commentLength = Math.min(commentBytes.length, 0xFFFF); // Max 65535 bytes
-
-    const buffer = Buffer.alloc(22 + commentLength);
-    let offset = 0;
-
-    // End of central directory signature (4 bytes)
-    buffer.writeUInt32LE(0x06054b50, offset);
-    offset += 4;
-
-    // Number of this disk (2 bytes)
-    buffer.writeUInt16LE(0, offset);
-    offset += 2;
-
-    // Number of the disk with the start of the central directory (2 bytes)
-    buffer.writeUInt16LE(0, offset);
-    offset += 2;
-
-    // Total number of entries in the central directory on this disk (2 bytes)
-    buffer.writeUInt16LE(totalEntries, offset);
-    offset += 2;
-
-    // Total number of entries in the central directory (2 bytes)
-    buffer.writeUInt16LE(totalEntries, offset);
-    offset += 2;
-
-    // Size of the central directory (4 bytes)
-    buffer.writeUInt32LE(centralDirSize, offset);
-    offset += 4;
-
-    // Offset of start of central directory with respect to the starting disk number (4 bytes)
-    buffer.writeUInt32LE(centralDirOffset, offset);
-    offset += 4;
-
-    // ZIP file comment length (2 bytes)
-    buffer.writeUInt16LE(commentLength, offset);
-    offset += 2;
-
-    // ZIP file comment (variable length)
-    if (commentLength > 0) {
-      commentBytes.copy(buffer, offset, 0, commentLength);
-    }
+    const buffer = buildEndRecords({
+      totalEntries,
+      centralDirSize,
+      centralDirOffset,
+      zip64EocdOffset: centralDirOffset + centralDirSize,
+      archiveComment,
+      allowSizeOffsetZip64: true,
+      forceZip64: options?.forceZip64 === true,
+    });
 
-    // Write EOCD to file
+    // Write EOCD (and Zip64 EOCD + locator when needed) to file
     await new Promise<void>((resolve, reject) => {
       writer.outputStream.write(buffer, (error) => {
         if (error) {
@@ -989,7 +1097,9 @@ export default class ZipkitNode extends Zipkit {
         writer,
         entries.length,
         centralDirSize,
-        centralDirOffset
+        centralDirOffset,
+        undefined,
+        { forceZip64: options?.forceZip64 === true }
       );
     } finally {
       await this.finalizeZipFile(writer);
@@ -1132,6 +1242,21 @@ export default class ZipkitNode extends Zipkit {
     throw new Error('updateZipFile() - Full implementation pending. Use neozip CLI for now.');
   }
 
+  /**
+   * Stream members to `filePath` (local headers, payloads, central directory, EOCD).
+   * Pass `useSHA256` for Extra Field 0x014E and `additionalExtra` for caller blocks
+   * such as ZipWiki 0x014F. `method` 93 uses zlib zstd at `level` (default 7).
+   * NeoEncrypt is not enabled. Precompressed members are copied without recompression.
+   * Pass `{ forceZip64: true }` to emit Zip64 even for small members (testing).
+   */
+  writeMembersSync(
+    filePath: string,
+    members: ZipBufferMember[],
+    options?: BuildZipBufferOptions
+  ): void {
+    writeZipFileSync(filePath, members, options);
+  }
+
   // ============================================================================
   // File-based ZIP Loading Methods (merged from ZipLoadEntriesServer)
   // ============================================================================
@@ -1197,9 +1322,17 @@ export default class ZipkitNode extends Zipkit {
         const zipkit = this as any;
         zipkit.centralDirSize = eocdBuffer.readUInt32LE(CENTRAL_END.CENTRAL_DIR_SIZE);
         zipkit.centralDirOffset = eocdBuffer.readUInt32LE(CENTRAL_END.CENTRAL_DIR_OFFSET);
-        
-        // Handle ZIP64
-        if (zipkit.centralDirOffset === 0xFFFFFFFF) {
+        const volEntries = eocdBuffer.readUInt16LE(CENTRAL_END.VOL_ENTRIES);
+        const totalEntries = eocdBuffer.readUInt16LE(CENTRAL_END.TOTAL_ENTRIES);
+
+        if (
+          classicEocdNeedsZip64({
+            volEntries,
+            totalEntries,
+            centralDirSize: zipkit.centralDirSize,
+            centralDirOffset: zipkit.centralDirOffset,
+          })
+        ) {
           await this.loadZIP64EOCD(eocdOffset);
         }
       } else {
@@ -1229,20 +1362,18 @@ export default class ZipkitNode extends Zipkit {
     }
     
     // Look for ZIP64 locator
-    const locatorOffset = eocdOffset - 20;
-    const locatorBuffer = Buffer.alloc(20);
-    await this.fileHandle.read(locatorBuffer, 0, 20, locatorOffset);
+    const locatorOffset = eocdOffset - ZIP64_LOCATOR_SIZE;
+    const locatorBuffer = Buffer.alloc(ZIP64_LOCATOR_SIZE);
+    await this.fileHandle.read(locatorBuffer, 0, ZIP64_LOCATOR_SIZE, locatorOffset);
     
-    if (locatorBuffer.readUInt32LE(0) === ZIP64_CENTRAL_END.SIGNATURE) {
-      // Read ZIP64 EOCD
-      const zip64Offset = locatorBuffer.readBigUInt64LE(8);
-      const zip64Buffer = Buffer.alloc(56);
-      await this.fileHandle.read(zip64Buffer, 0, 56, Number(zip64Offset));
-      
-      const zipkit = this as any;
-      zipkit.centralDirSize = Number(zip64Buffer.readBigUInt64LE(ZIP64_CENTRAL_DIR.CENTRAL_DIR_SIZE));
-      zipkit.centralDirOffset = Number(zip64Buffer.readBigUInt64LE(ZIP64_CENTRAL_DIR.CENTRAL_DIR_OFFSET));
-    }
+    const zip64Offset = parseZip64Locator(locatorBuffer);
+    const zip64Buffer = Buffer.alloc(ZIP64_EOCD_RECORD_SIZE);
+    await this.fileHandle.read(zip64Buffer, 0, ZIP64_EOCD_RECORD_SIZE, zip64Offset);
+    
+    const z64 = parseZip64Eocd(zip64Buffer);
+    const zipkit = this as any;
+    zipkit.centralDirSize = z64.centralDirSize;
+    zipkit.centralDirOffset = z64.centralDirOffset;
   }
 
   /**

package/src/node/ZstdNode.ts

@@ -54,26 +54,49 @@ export function createDecompressTransform(): zlib.ZstdDecompress {
   return zlib.createZstdDecompress();
 }
 
-export async function compress(data: Buffer, level: number = 6): Promise<Buffer> {
+/** Bytes accepted by the buffer zstd codec (Node Buffer or browser ArrayBuffer). */
+export type ZstdInput = Buffer | Uint8Array | ArrayBuffer;
+
+export function asZstdBuffer(data: ZstdInput): Buffer {
+  if (Buffer.isBuffer(data)) return data;
+  if (data instanceof ArrayBuffer) return Buffer.from(data);
+  return Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+}
+
+export async function compress(data: ZstdInput, level: number = 6): Promise<Buffer> {
   assertNativeZstd();
-  const result = await zstdCompressAsync(data, compressOptions(level));
+  const result = await zstdCompressAsync(asZstdBuffer(data), compressOptions(level));
   return Buffer.from(result);
 }
 
-export async function decompress(data: Buffer): Promise<Buffer> {
+export async function decompress(data: ZstdInput): Promise<Buffer> {
   assertNativeZstd();
-  const result = await zstdDecompressAsync(data);
+  const result = await zstdDecompressAsync(asZstdBuffer(data));
   return Buffer.from(result);
 }
 
-export function compressSync(data: Buffer, level: number = 6): Buffer {
+export function compressSync(data: ZstdInput, level: number = 6): Buffer {
+  assertNativeZstd();
+  return zlib.zstdCompressSync(asZstdBuffer(data), compressOptions(level));
+}
+
+/**
+ * Compress with a raw zlib zstd level (1–19), without the 1–9 kit scale.
+ * ZipWiki pack uses level 7 on this scale.
+ */
+export function compressSyncAtLevel(data: ZstdInput, zstdLevel: number): Buffer {
   assertNativeZstd();
-  return zlib.zstdCompressSync(data, compressOptions(level));
+  const level = Math.min(19, Math.max(1, Math.trunc(zstdLevel)));
+  return zlib.zstdCompressSync(asZstdBuffer(data), {
+    params: {
+      [zlib.constants.ZSTD_c_compressionLevel]: level,
+    },
+  });
 }
 
-export function decompressSync(data: Buffer): Buffer {
+export function decompressSync(data: ZstdInput): Buffer {
   assertNativeZstd();
-  return zlib.zstdDecompressSync(data);
+  return zlib.zstdDecompressSync(asZstdBuffer(data));
 }
 
 /**
@@ -147,7 +170,9 @@ export const ZstdNode = {
   compress,
   decompress,
   compressSync,
+  compressSyncAtLevel,
   decompressSync,
+  asZstdBuffer,
   compressChunks,
   decompressStream,
 };