neozipkit 0.7.2 → 1.0.2

package/README.md

@@ -4,13 +4,9 @@ Advanced ZIP file creation, compression, and encryption library for Node.js and
 
 **Scope of this package:** NeoZipKit focuses solely on creating and manipulating ZIP files (compression, encryption, extraction). All blockchain-related functionality—timestamping, NFT tokenization, verification, wallet integration, and smart contracts—lives in the sibling **[neozip-blockchain](../neozip-blockchain/)** package within this monorepo. Use that package when you need to link ZIPs to the blockchain.
 
-> **⚠️ Beta Version Warning**: NeoZipKit is currently in **beta** status. This means:
-> - The API may change in future releases
-> - Some features may be incomplete or experimental
-> - Breaking changes may occur before the stable release
-> - Use in production with caution and thorough testing
->
-> We welcome feedback and contributions! Please report issues on [GitHub](https://github.com/NeoWareInc/neozipkit/issues). This package is part of the [neozipkit monorepo](../../README.md).
+> **Stable 1.0:** NeoZipKit **1.0.2** is the first non-beta release. Please report issues on [GitHub](https://github.com/NeoWareInc/neozipkit/issues). This package is part of the [neozipkit monorepo](../../README.md).
+
+
 
 ## Features
 
@@ -22,10 +18,12 @@ Advanced ZIP file creation, compression, and encryption library for Node.js and
 - **Browser and Node.js compatibility** with clean platform separation
 - **TypeScript support** with full type definitions
 
+
+
 ## Installation
 
 ```bash
-yarn add neozipkit
+pnpm add neozipkit
 ```
 
 Or with npm:
@@ -34,8 +32,12 @@ Or with npm:
 npm install neozipkit
 ```
 
+
+
 ## Quick Start
 
+
+
 ### Node.js
 
 ```typescript
@@ -50,6 +52,8 @@ await zip.createZipFromFiles(['file1.txt', 'file2.txt'], 'output.zip');
 await zip.extractZipFile('archive.zip', './output');
 ```
 
+
+
 ### Browser
 
 ```typescript
@@ -60,32 +64,53 @@ await zip.addFile(file, { level: 6 });
 const zipBlob = await zip.createZipBlob();
 ```
 
+
+
 ### Examples
 
-Runnable examples live **only in this repository**—they are **not** shipped in the [npm package](https://www.npmjs.com/package/neozipkit) (`package.json` `"files"` is `dist/`, `src/`, and `README.md`). Browse or clone the repo to use them.
+Runnable examples live **only in this repository**—they are **not** shipped in the [npm package](https://www.npmjs.com/package/neozipkit). Browse or clone the repo to use them.
 
 On GitHub: [`packages/neozipkit/examples/`](https://github.com/NeoWareInc/neozipkit/tree/main/packages/neozipkit/examples) — see [`examples/README.md`](examples/README.md) for scripts (create/extract/list/copy ZIP, AES demos, encrypted listing) and how to run them from a checkout.
 
 ```bash
-# From monorepo root, after yarn install
+# From monorepo root, after pnpm install
 cd packages/neozipkit
 npx ts-node examples/create-zip.ts
 ```
 
+
+
 ## Blockchain integration
 
 All blockchain code lives in the sibling **[neozip-blockchain](../neozip-blockchain/)** package within this monorepo. For timestamping, NFT tokenization, on-chain verification, wallet management, and OpenTimestamps, install `neozip-blockchain` alongside this package. It depends on `neozipkit` for ZIP handling and adds all blockchain features on top. NeoZipKit itself contains no blockchain, contract, or wallet code.
 
 ## Package layout
 
-- **`neozipkit`** – Main entry (core + platform detection)
-- **`neozipkit/node`** – Node.js-only (ZipkitNode, file I/O, streaming)
-- **`neozipkit/browser`** – Browser-only (ZipkitBrowser, Blob API)
-- **`neozipkit/browser-esm`** – Browser ESM bundle (tree-shaking)
+- `neozipkit` – Main entry (core + platform detection)
+- `neozipkit/node` – Node.js-only (ZipkitNode, file I/O, streaming)
+- `neozipkit/browser` – Browser-only (ZipkitBrowser, Blob API)
+- `neozipkit/browser-esm` – Browser ESM bundle (tree-shaking)
+
+
+
+## I/O model (aligned with Rust NeoZipKit)
+
+**Node / CLI product path:** one streaming (chunked) engine — read → hash → compress/encrypt → write in ~512 KiB buffers. There is no separate full-archive “VM / in-memory” mode. Small entries may still use an in-API buffer fast path inside the same APIs.
+
+
+| Surface                                 | Behavior                                                                                                      |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `ZipkitNode` create / extract / list    | File streaming (`loadZipFile`, `writeZipEntry`, `extractToFile`, …)                                           |
+| Core `Zipkit.loadZip(Buffer)` / browser | Buffer APIs kept for browser and small in-process buffers                                                     |
+| Zstd (method 93)                        | Node native `zlib` Transform streams only (no WASM). Requires Node ≥ 22.15                                    |
+| Legacy WASM zstd archives               | Detect with `detectLegacyWasmZstd` / `ZipkitNode.detectLegacyZstdEntries`; extract truncates +18 zero padding |
+
+
+See also: [docs/ZSTD_USAGE.md](docs/ZSTD_USAGE.md) and the Rust crate notes in `neozip-rust` (`crates/neozipkit/src/limits.rs`).
 
 ## Publishing (npm)
 
-The published tarball includes **`dist/`**, **`src/`** (for `neozipkit/src` conditional exports), and the **package root [`README.md`](README.md)** only. **`examples/`** and other repo-only folders are excluded—use **`yarn publish:dry-run`** (`npm publish --dry-run`) to preview the file list.
+The published tarball includes **`dist/`**, **`src/`** (for `neozipkit/src` conditional exports), **[`README.md`](README.md)**, and **[`WHATS_NEW.md`](WHATS_NEW.md)**. **`examples/`** and other repo-only folders are excluded—use **`pnpm publish:dry-run`** (`npm publish --dry-run`) to preview the file list.
 
 ## Development
 
@@ -93,30 +118,32 @@ This package is part of the [neozipkit monorepo](../../README.md). From the **re
 
 ```bash
 # Install all dependencies
-yarn install
+pnpm install
 
 # Build all packages (topological order)
-yarn build
+pnpm build
 
 # Run all unit tests
-yarn test:unit
+pnpm test:unit
 ```
 
 To work on this package alone:
 
 ```bash
 cd packages/neozipkit
-yarn build
-yarn test
+pnpm build
+pnpm test
 ```
 
-See [`docs/DEV_BUILD.md`](docs/DEV_BUILD.md) for the development build system and the [monorepo README](../../README.md) for version management and release workflow.
+See `[docs/DEV_BUILD.md](docs/DEV_BUILD.md)` for the development build system and the [monorepo README](../../README.md) for version management and release workflow.
 
 ## API overview
 
+
+
 ### ZipkitNode and file handles (Node.js)
 
-`ZipkitNode.loadZipFile()` opens the archive with `fs.promises.open()`. You should call **`closeFile()`** when you are done reading so the `FileHandle` is released promptly. Node deprecates relying on garbage collection to close handles ([DEP0137](https://nodejs.org/api/deprecations.html#DEP0137)).
+`ZipkitNode.loadZipFile()` opens the archive with `fs.promises.open()`. You should call `closeFile()` when you are done reading so the `FileHandle` is released promptly. Node deprecates relying on garbage collection to close handles ([DEP0137](https://nodejs.org/api/deprecations.html#DEP0137)).
 
 As of **v0.6.1**, `loadZipFile()` automatically **closes any prior read handle** before loading another path on the **same** instance, so reusing a `ZipkitNode` does not leak descriptors. `closeFile()` remains the right way to finish with the current archive.
 
@@ -131,21 +158,27 @@ As of **v0.6.1**, `loadZipFile()` automatically **closes any prior read handle**
 - **EncryptionManager** / **ZipCrypto** – Legacy ZIP encryption
 - **AesCrypto** / **EncryptionMethod.AES_256** – AES-256 encryption (WinZip AE-1/AE-2)
 
+
+
 ### Compression methods
 
 - **STORED (0)** – No compression
 - **DEFLATED (8)** – Deflate (default)
 - **ZSTD (93)** – Zstandard
 
+
+
 ### Encryption
 
 - **ZIP (Legacy)** – Classic ZIP encryption; use `password` in options (no `encryptionMethod`).
 - **AES-256** – WinZip-compatible (AE-1/AE-2); use `password` and `encryptionMethod: 'aes256'` in compress options. Create and extract supported in Node and browser. See [WHATS_NEW.md](WHATS_NEW.md#060-2025-01-27) for details. For on-disk layout (headers, extra field 0x9901), AE-1 vs AE-2, and how this differs from ZipCrypto and PKWARE strong encryption, see [docs/WINZIP_AES_FORMAT.md](docs/WINZIP_AES_FORMAT.md).
 - **NeoEncrypt (NEO AES-256)** – NeoZip-specific: use `password` and `encryptionMethod: 'neo-aes256'`. The LO/CEN compression method stays a normal ZIP code (e.g. deflate, zstd); encryption is indicated by the encrypted flag plus extra field `0x024E`. Ciphertext layout matches the WinZip AES stream (PBKDF2, CTR, HMAC). Specification: [docs/NEO_CRYPTO_FORMAT.md](docs/NEO_CRYPTO_FORMAT.md).
 
+
+
 ## What’s new
 
-See [WHATS_NEW.md](WHATS_NEW.md) for release notes. **v0.6.1** fixes **ZipkitNode** read handle lifecycle (reuse and failed loads; see above). **v0.6.0** adds full **AES-256 encryption** (create and extract, Node and browser, WinZip-compatible).
+See [WHATS_NEW.md](WHATS_NEW.md) for release notes. 
 
 ## Security
 
@@ -153,4 +186,4 @@ See [SECURITY.md](SECURITY.md) for security considerations and best practices.
 
 ## License
 
-MIT
+MIT

package/WHATS_NEW.md

@@ -0,0 +1,114 @@
+# What’s New in NeoZipKit
+
+Release notes for people who install and use **`neozipkit`** from npm. For blockchain timestamping and NFTs, see the sibling package [`neozip-blockchain`](https://www.npmjs.com/package/neozip-blockchain).
+
+## 1.0.2 (2026-07-28)
+
+### First stable release
+
+**1.0.2** is the first non-beta release. From here on, NeoZipKit follows [Semantic Versioning](https://semver.org/): breaking API changes bump the major version.
+
+*(Versions `1.0.0` / `1.0.1` were reserved earlier on npm and are not used for this stable line.)*
+
+### Zstandard compression (Node.js)
+
+Zstd (ZIP method **93**) now uses **Node.js built-in `zlib` streaming**. The previous WASM-based codec is removed.
+
+**What this means for you:**
+
+- Use Zstd only on **Node.js ≥ 22.15** or **≥ 23.8**.
+- Archives are compatible with other tools that support ZIP method 93 / libzstd.
+- Large files stay memory-efficient (chunked streaming, default buffer ~512 KiB).
+- **Browsers do not support Zstd.** Use Deflate (or Stored) in the browser, or create/extract Zstd archives in Node.
+
+```ts
+import { ZipkitNode } from 'neozipkit/node';
+
+const zip = new ZipkitNode();
+await zip.createZipFromFiles(['file1.txt', 'file2.txt'], 'output.zip', {
+  useZstd: true,
+  level: 6,
+});
+```
+
+**Upgrading from older NeoZipKit Zstd archives:** Older releases wrote frames with a small padding quirk. Extract still works; you can also scan an archive:
+
+```ts
+const hits = await zip.detectLegacyZstdEntries('old-archive.zip');
+for (const { entry, detection } of hits) {
+  if (detection.isLegacyWasm) {
+    console.log(entry.filename, detection.confidence, detection.reason);
+  }
+}
+```
+
+### Streaming-first I/O (Node)
+
+Node create/extract/list paths are **streaming** (read → hash → compress/encrypt → write in chunks). There is no separate “load the whole archive into a VM” mode.
+
+- Prefer `ZipkitNode` file APIs for disk workflows.
+- Buffer APIs remain for the browser and small in-process use cases.
+
+### Compatibility snapshot
+
+| Environment | Deflate / Stored | Zstd | AES-256 / NeoEncrypt / ZipCrypto |
+|-------------|------------------|------|-----------------------------------|
+| Node.js (see version above for Zstd) | Yes | Yes | Yes |
+| Browser (ESM / UMD) | Yes | No | Yes |
+
+---
+
+## 0.6.1 (2026-03-30)
+
+### More reliable file handle reuse (Node.js)
+
+If you call `loadZipFile()` more than once on the same `ZipkitNode` instance, NeoZipKit now **closes the previous read handle** before opening the next file. Failed loads also clean up so handles are not left open. `closeFile()` clears path/size metadata so “closed” means no archive is loaded.
+
+This avoids descriptor leaks and Node’s `FileHandle` GC deprecation warning when reusing a `ZipkitNode`.
+
+---
+
+## 0.6.0 (2025-01-27)
+
+### AES-256 encryption
+
+Full **WinZip-compatible AES-256 (AE-1/AE-2)** support, in addition to legacy ZIP encryption.
+
+- Create and extract encrypted ZIPs in **Node and the browser**.
+- Interop with WinZip, 7-Zip, The Unarchiver (`unar`/`lsar`), and other AE-1/AE-2 tools.
+
+**Create:**
+
+```ts
+const zip = new ZipkitNode();
+await zip.createZipFromFiles(
+  ['file1.txt', 'file2.txt'],
+  'secure.zip',
+  {
+    password: 'YourStrongPassword',
+    encryptionMethod: 'aes256',
+    level: 6,
+  }
+);
+```
+
+**Extract:**
+
+```ts
+await zip.extractZipFile('secure.zip', './out', {
+  password: 'YourStrongPassword',
+});
+```
+
+**How it works (summary):** PBKDF2-HMAC-SHA1 (1000 iterations), AES-256-CTR (WinZip little-endian counter), HMAC-SHA1 over ciphertext (10-byte auth code per entry).
+
+Also in this release:
+
+- Encryption bit set correctly on all encrypted local headers (including the last entry).
+- Copy/append helpers for building archives by copying entries then finalizing the central directory.
+
+**NeoEncrypt** (NeoZip-specific AES via extra field `0x024E`, normal compression method in headers) is available with `encryptionMethod: 'neo-aes256'`. See the package README for details.
+
+---
+
+For password handling and security notes, see the [SECURITY.md](https://github.com/NeoWareInc/neozipkit/blob/main/packages/neozipkit/SECURITY.md) in the repository.

package/dist/browser/zstd-browser-shim.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Browser stub for ZSTD — native zlib streaming is Node-only.
+ * Browser builds alias `ZstdNode` to this module so the bad WASM codec is never shipped.
+ */
+export declare function isNativeZstdAvailable(): boolean;
+export declare function mapCompressionLevel(_level: number): number;
+export declare function createCompressTransform(_level?: number): never;
+export declare function createDecompressTransform(): never;
+export declare function compress(_data: Buffer, _level?: number): Promise<Buffer>;
+export declare function decompress(_data: Buffer): Promise<Buffer>;
+export declare function compressSync(_data: Buffer, _level?: number): Buffer;
+export declare function decompressSync(_data: Buffer): Buffer;
+export declare function compressChunks(_readChunk: (position: number, size: number) => Buffer, _totalSize: number, _chunkSize: number, _level: number, _onPlainChunk?: (chunk: Buffer) => void, _onCompressedChunk?: (chunk: Buffer) => void | Promise<void>): Promise<number>;
+export declare function decompressStream(_compressedStream: AsyncIterable<Buffer>): AsyncGenerator<Buffer>;
+export declare const ZstdNode: {
+    isNativeZstdAvailable: typeof isNativeZstdAvailable;
+    mapCompressionLevel: typeof mapCompressionLevel;
+    createCompressTransform: typeof createCompressTransform;
+    createDecompressTransform: typeof createDecompressTransform;
+    compress: typeof compress;
+    decompress: typeof decompress;
+    compressSync: typeof compressSync;
+    decompressSync: typeof decompressSync;
+    compressChunks: typeof compressChunks;
+    decompressStream: typeof decompressStream;
+};
+export default ZstdNode;
+//# sourceMappingURL=zstd-browser-shim.d.ts.map

package/dist/browser/zstd-browser-shim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd-browser-shim.d.ts","sourceRoot":"","sources":["../../src/browser/zstd-browser-shim.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAUH,wBAAgB,qBAAqB,IAAI,OAAO,CAE/C;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED,wBAAgB,uBAAuB,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAE9D;AAED,wBAAgB,yBAAyB,IAAI,KAAK,CAEjD;AAED,wBAAsB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE9E;AAED,wBAAsB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE/D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAsB,cAAc,CAClC,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,EACtD,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,EACvC,kBAAkB,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAC3D,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED,wBAAuB,gBAAgB,CACrC,iBAAiB,EAAE,aAAa,CAAC,MAAM,CAAC,GACvC,cAAc,CAAC,MAAM,CAAC,CAExB;AAED,eAAO,MAAM,QAAQ;;;;;;;;;;;CAWpB,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/dist/browser/zstd-browser-shim.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Browser stub for ZSTD — native zlib streaming is Node-only.
+ * Browser builds alias `ZstdNode` to this module so the bad WASM codec is never shipped.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ZstdNode = void 0;
+exports.isNativeZstdAvailable = isNativeZstdAvailable;
+exports.mapCompressionLevel = mapCompressionLevel;
+exports.createCompressTransform = createCompressTransform;
+exports.createDecompressTransform = createDecompressTransform;
+exports.compress = compress;
+exports.decompress = decompress;
+exports.compressSync = compressSync;
+exports.decompressSync = decompressSync;
+exports.compressChunks = compressChunks;
+exports.decompressStream = decompressStream;
+const ZSTD_BROWSER_UNSUPPORTED = 'ZSTD requires Node.js with native zlib support (Node.js >= 22.15 or >= 23.8). ' +
+    'Browser builds do not include a zstd codec; use Deflate or process zstd archives in Node.';
+function unsupported() {
+    throw new Error(ZSTD_BROWSER_UNSUPPORTED);
+}
+function isNativeZstdAvailable() {
+    return false;
+}
+function mapCompressionLevel(_level) {
+    return unsupported();
+}
+function createCompressTransform(_level) {
+    return unsupported();
+}
+function createDecompressTransform() {
+    return unsupported();
+}
+async function compress(_data, _level) {
+    return unsupported();
+}
+async function decompress(_data) {
+    return unsupported();
+}
+function compressSync(_data, _level) {
+    return unsupported();
+}
+function decompressSync(_data) {
+    return unsupported();
+}
+async function compressChunks(_readChunk, _totalSize, _chunkSize, _level, _onPlainChunk, _onCompressedChunk) {
+    return unsupported();
+}
+async function* decompressStream(_compressedStream) {
+    unsupported();
+}
+exports.ZstdNode = {
+    isNativeZstdAvailable,
+    mapCompressionLevel,
+    createCompressTransform,
+    createDecompressTransform,
+    compress,
+    decompress,
+    compressSync,
+    decompressSync,
+    compressChunks,
+    decompressStream,
+};
+exports.default = exports.ZstdNode;
+//# sourceMappingURL=zstd-browser-shim.js.map

package/dist/browser/zstd-browser-shim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zstd-browser-shim.js","sourceRoot":"","sources":["../../src/browser/zstd-browser-shim.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAUH,sDAEC;AAED,kDAEC;AAED,0DAEC;AAED,8DAEC;AAED,4BAEC;AAED,gCAEC;AAED,oCAEC;AAED,wCAEC;AAED,wCASC;AAED,4CAIC;AAvDD,MAAM,wBAAwB,GAC5B,gFAAgF;IAChF,2FAA2F,CAAC;AAE9F,SAAS,WAAW;IAClB,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAC5C,CAAC;AAED,SAAgB,qBAAqB;IACnC,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAgB,mBAAmB,CAAC,MAAc;IAChD,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AAED,SAAgB,uBAAuB,CAAC,MAAe;IACrD,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AAED,SAAgB,yBAAyB;IACvC,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AAEM,KAAK,UAAU,QAAQ,CAAC,KAAa,EAAE,MAAe;IAC3D,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AAEM,KAAK,UAAU,UAAU,CAAC,KAAa;IAC5C,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AAED,SAAgB,YAAY,CAAC,KAAa,EAAE,MAAe;IACzD,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AAED,SAAgB,cAAc,CAAC,KAAa;IAC1C,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AAEM,KAAK,UAAU,cAAc,CAClC,UAAsD,EACtD,UAAkB,EAClB,UAAkB,EAClB,MAAc,EACd,aAAuC,EACvC,kBAA4D;IAE5D,OAAO,WAAW,EAAE,CAAC;AACvB,CAAC;AAEM,KAAK,SAAS,CAAC,CAAC,gBAAgB,CACrC,iBAAwC;IAExC,WAAW,EAAE,CAAC;AAChB,CAAC;AAEY,QAAA,QAAQ,GAAG;IACtB,qBAAqB;IACrB,mBAAmB;IACnB,uBAAuB;IACvB,yBAAyB;IACzB,QAAQ;IACR,UAAU;IACV,YAAY;IACZ,cAAc;IACd,cAAc;IACd,gBAAgB;CACjB,CAAC;AAEF,kBAAe,gBAAQ,CAAC"}