neozip-mcp 0.8.0-beta.2 → 0.9.5-beta

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. package/CHANGELOG.md +55 -0
  2. package/README.md +29 -9
  3. package/SECURITY.md +1 -1
  4. package/dist/archive/blockchain-status.js +10 -21
  5. package/dist/archive/embed-metadata.js +36 -14
  6. package/dist/archive/encryption.js +16 -0
  7. package/dist/archive/extract-entry-buffer.js +25 -6
  8. package/dist/archive/manifest.js +6 -1
  9. package/dist/archive/merkle.js +62 -20
  10. package/dist/archive/metadata-paths.js +25 -9
  11. package/dist/archive/native-zstd.js +49 -0
  12. package/dist/archive/open-archive.js +28 -0
  13. package/dist/archive/recipient-access.js +1 -1
  14. package/dist/archive/recipient-decrypt.js +1 -1
  15. package/dist/config/capabilities.js +1 -1
  16. package/dist/config/index.js +18 -4
  17. package/dist/connect-cli.js +41 -0
  18. package/dist/connection/cli-prefs.js +213 -0
  19. package/dist/connection/cli-settings.js +108 -0
  20. package/dist/connection/funding.js +10 -1
  21. package/dist/connection/interactive.js +16 -9
  22. package/dist/connection/membership.js +259 -0
  23. package/dist/connection/origin.js +70 -4
  24. package/dist/connection/store.js +2 -1
  25. package/dist/connection/token-auth.js +29 -2
  26. package/dist/constants/wallet-identity.js +1 -1
  27. package/dist/index.js +1 -1
  28. package/dist/prune/detect.js +67 -0
  29. package/dist/prune/errors.js +11 -0
  30. package/dist/prune/inputs.js +44 -0
  31. package/dist/prune/read-entry.js +49 -0
  32. package/dist/register/tools.js +27 -9
  33. package/dist/resources/zip-resource.js +20 -23
  34. package/dist/security/capabilities.js +10 -0
  35. package/dist/server.js +2 -2
  36. package/dist/tools/compress.js +5 -1
  37. package/dist/tools/extract.js +64 -27
  38. package/dist/tools/grep-entries.js +19 -13
  39. package/dist/tools/info.js +110 -98
  40. package/dist/tools/list.js +84 -77
  41. package/dist/tools/mint.js +7 -1
  42. package/dist/tools/prune.js +142 -0
  43. package/dist/tools/read-entry.js +15 -9
  44. package/dist/tools/search-entries.js +49 -43
  45. package/dist/tools/stamp.js +31 -29
  46. package/dist/tools/test.js +101 -55
  47. package/dist/tools/upgrade.js +2 -1
  48. package/dist/tools/verify.js +42 -47
  49. package/dist/tools/wiki.js +228 -0
  50. package/dist/wiki/adapter.js +109 -0
  51. package/docs/NEOZIP_CONNECTION_STORE.md +1 -0
  52. package/docs/NEOZIP_CONNECT_CLI.md +8 -3
  53. package/docs/OPERATIONS.md +196 -14
  54. package/docs/examples/CLAUDE.md.example +1 -1
  55. package/docs/examples/claude/skills/neozip-mcp/SKILL.md +24 -4
  56. package/docs/examples/claude/skills/neozip-notarization/SKILL.md +3 -2
  57. package/docs/examples/neozip-mcp-cursor-rule.mdc +4 -0
  58. package/docs/installation-guides/INSTALL_CLAUDE_CODE.md +10 -3
  59. package/docs/installation-guides/INSTALL_CLAUDE_WORKSPACE.md +3 -3
  60. package/docs/installation-guides/README.md +2 -1
  61. package/package.json +21 -21
  62. package/dist/vendor/neozipkit-pro.js +0 -3
package/CHANGELOG.md CHANGED
@@ -2,6 +2,61 @@
2
2
 
3
3
  Release notes for [neozip-mcp](https://www.npmjs.com/package/neozip-mcp).
4
4
 
5
+ ## Unreleased
6
+
7
+ ## 0.9.5-beta (2026-11-22)
8
+
9
+ - **neozip-prune 0.5.0.** Pruned archives use the 0.5.0 format: shared parts
10
+ are method 209 (`PruneItem` in `list` / `info`) and each pruned entry names
11
+ its real codec in Extra Field `0x034E`. **Breaking:** archives created by
12
+ 0.9.0-beta (neozip-prune 0.1.0) cannot be read; extract them with 0.9.0-beta
13
+ and run `prune_create` again.
14
+ - **PDF pruning disabled.** `prune_analyze` and `prune_create` store PDFs whole
15
+ (`mode: "plain"`, reason `PDF pruning is off`) until PDF stream pruning is
16
+ ready. Office document pruning is unchanged. Pruned archives that other
17
+ NeoZip tools created with PDF parts can still be read and extracted.
18
+ - **SHA-256 kept.** `prune_create` still records each file's SHA-256 (neozip-prune
19
+ now omits it by default), so `extract` / `test` check size, CRC-32 and SHA-256.
20
+ - `read_entry` on a `META-INF/PRUNE/ITEMS/` shared part now explains that it is
21
+ not a user file.
22
+ - **Agent plugin (`plugins/neozip`).** Portable Agent Plugins package in-repo
23
+ (Claude / Cursor / Grok Bot): launches `neozip-mcp@0.9.5-beta` via `npx`, ships
24
+ archive + notarization skills and a Cursor rule. Marketplace index at
25
+ `.cursor-plugin/marketplace.json`. See `plugins/neozip/README.md`.
26
+
27
+ ## 0.9.0-beta (2026-11-15)
28
+
29
+ - **Pruned archives (beta).** New `prune_analyze`, `prune_create`, and
30
+ `prune_info` tools use `neozip-prune` (same library as `neozip prune` in
31
+ NeoZip CLI) to store parts shared across Office documents and PDFs once in a
32
+ `.nzip`. `extract`, `test`, `read_entry`, `grep_entries`, `info`, `list`, and
33
+ `zip://` resources rebuild method 208 entries with size / CRC-32 / SHA-256
34
+ checks, but only when a valid `META-INF/PRUNE.NZIP` manifest is present;
35
+ regular ZIP / NZIP / ZipWiki archives are unchanged. `stamp` refuses pruned
36
+ archives. New `prune` capability group; `prune_analyze` / `prune_info` are
37
+ also in `readonly`, all three in `zip`.
38
+ - **ZipWiki query tools.** New `wiki_open`, `wiki_search`, `wiki_query`,
39
+ `wiki_read`, `wiki_extract`, `wiki_origin`, and `wiki_verify` query `.zipwiki`
40
+ knowledge packages via `neozip-wiki` (same library as `neozip wiki` in
41
+ NeoZip CLI). Paths are sandbox-validated; the default package is
42
+ `wiki.zipwiki` in a sandbox root. ZipWiki handling applies only when the
43
+ manifest declares the `"zipwiki"` profile; regular ZIP / NZIP archives keep
44
+ using the existing tools unchanged. `wiki_origin` fetching is off unless
45
+ `NEOZIP_MCP_WIKI_ALLOW_ORIGIN_FETCH=true`. New `wiki` capability group; read
46
+ tools are also in `readonly`, all wiki tools in `zip`.
47
+ - **neozipkit / neozip-blockchain 1.6.3.** `neozip-blockchain/ots` is gone;
48
+ archive Merkle roots now call `ZipkitNode.getMerkleRootAsync()` directly.
49
+ Recipient encryption uses public `neozip-blockchain/encryption` and
50
+ `neozip-blockchain/identity` (retired `@neowareinc/neozipkit-pro`).
51
+ `switch-neozipkit.mjs` also switches `neozip-wiki` / `neozip-prune` and
52
+ installs with `--ignore-workspace`.
53
+ - **Dual-era MCP 2026-07-28.** The stdio server now uses `@prefecthq/fastmcp-ts` so one process answers both the legacy `initialize` handshake (Claude Code / Cursor) and the stateless 2026-07-28 era (`server/discover` / `_meta`). Do not expect a modern-only server — mixed hosts would fail. Completions use empty `complete` callbacks instead of pinning MCP SDK 1.21.2.
54
+ - **Merkle v1 (APPNOTE §6).** Archive roots come from `getMerkleRootAsync()` (default v1). Verify uses `matchMerkleRoot` (v1 then v0). META-INF discovery is ASCII case-insensitive (`isMetaInfPath` / `findReservedMetaEntry`). HashCalculator-sorted digest trees from 0.8.x are neither APPNOTE v0 nor v1 — re-stamp or rely on v0 fallback when verifying older archives.
55
+ - **Token Service production and local.** `neozip-connect` wizard matches CLI: Testnet (Base Sepolia, free), Production (Base Mainnet, Stripe membership), Local (`localhost:14789`, Sepolia default, switchable to Mainnet), or Custom URL. Connection `defaultNetwork` is persisted from the origin; `NEOZIP_NETWORK` is a session override clamped to the origin allowlist.
56
+ - **Membership.** Production (and local sandbox) Token Service may return HTTP 402. Use `neozip-connect membership status | checkout | portal` in a terminal — MCP tools do not open Stripe Checkout. `stamp` / `mint` / `upgrade_timestamped` surface that guidance. `fund_wallet request` stays testnet-gated; production Base Mainnet funding is refused client-side.
57
+ - **Streaming I/O.** File/chunked create and extract, `extractToBuffer` for entry reads, ZipkitNode handles closed after use (avoids Node DEP0137). Zstd requires **Node.js >= 22.15**.
58
+ - **`neozip-connect settings`.** Change `defaultNetwork` / RPC after setup. Local origin may prompt to switch to Base Mainnet after `finish`.
59
+
5
60
  ## 0.8.0-beta.2 (2026-07-04)
6
61
 
7
62
  - **neozipkit & neozip-blockchain 0.8.0.** Production dependencies updated to
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  > MCP server for ZIP archives, blockchain notarization, and AI agent integration — powered by [neozipkit](https://www.npmjs.com/package/neozipkit) and [neozip-blockchain](https://www.npmjs.com/package/neozip-blockchain)
4
4
 
5
5
  [![npm version](https://img.shields.io/npm/v/neozip-mcp?label=beta&color=blue)](https://www.npmjs.com/package/neozip-mcp)
6
- [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
6
+ [![Node.js Version](https://img.shields.io/badge/node-%3E%3D22.15.0-brightgreen)](https://nodejs.org/)
7
7
 
8
8
  > **Beta version warning:** NeoZip MCP is currently in **beta** status. This means:
9
9
  > - The MCP tool surface and CLI may change in future releases
@@ -15,8 +15,11 @@
15
15
 
16
16
  ## Release notice
17
17
 
18
- **Current version: v0.8.0-beta.2.** See [CHANGELOG.md](CHANGELOG.md) for details.
18
+ **Current version: v0.9.5-beta.** See [CHANGELOG.md](CHANGELOG.md) for details.
19
19
 
20
+ - **Dual-era MCP:** Hosts that still send `initialize` (Claude Code, Cursor) keep working. Hosts that speak MCP 2026-07-28 get the stateless path automatically. One stdio process serves both.
21
+ - **Token Service:** Default remains hosted **testnet** (Base Sepolia). Production (Base Mainnet + Stripe membership) and local (`localhost:14789`) are first-class `neozip-connect` wizard choices.
22
+ - **Merkle v1:** Stamp/mint/verify use APPNOTE v1 roots (`getMerkleRootAsync`). Archives stamped with 0.8.x HashCalculator trees may need a new stamp or v0 fallback on verify.
20
23
  - **API stability:** MCP tool names and parameters may change before a stable release
21
24
  - **Testing:** Test thoroughly in your MCP host before production use
22
25
  - **Feedback:** Report issues via [GitHub Issues](https://github.com/NeoWareInc/neozip-support/issues) or email [support@neozip.io](mailto:support@neozip.io)
@@ -32,12 +35,28 @@ NeoZip MCP is a local stdio MCP server for AI coding agents (Claude Code, Cursor
32
35
  - **compress** -- Create ZIP archives (default: Zstandard). Options: `recipientEmails` (Token Service public-key encryption via `META-INF/ACCESS.NZIP`), `password` + `encryptionMethod`, `timestamp`, `tokenize`. SHA-256 is auto-enabled for timestamped/tokenized archives.
33
36
  - **extract** -- Extract ZIP files to directories (password-protected archives supported)
34
37
  - **list** -- List ZIP archive contents (text or JSON manifest)
35
- - **info** -- Get detailed ZIP metadata (sizes, ratios, merkle root)
38
+ - **info** -- Get detailed ZIP metadata (sizes, ratios, APPNOTE v1 merkle root)
36
39
  - **test** -- Test ZIP integrity per entry
37
40
  - **read_entry** -- Read a single file inside an archive with pagination (optional `options.password` for encrypted entries)
38
41
  - **search_entries** -- Search archive entry names by keyword or regex
39
42
  - **grep_entries** -- Search file contents inside an archive for text or regex matches (no extraction)
40
43
 
44
+ ### ZipWiki Packages (`.zipwiki`)
45
+ Query portable ZipWiki knowledge packages (OKF concept cards + parsed markdown) with the same `neozip-wiki` library as `neozip wiki` in NeoZip CLI. Create packages with ZipWiki (`zipwiki pack`).
46
+ - **wiki_open** -- Package catalog and recommended read sequence
47
+ - **wiki_search** -- Ranked search (OKF cards first, parsed markdown as evidence)
48
+ - **wiki_query** -- Search with cited passages and gaps
49
+ - **wiki_read** -- Stream-read the manifest, an OKF card, a parsed document, or any entry
50
+ - **wiki_extract** -- Integrity-checked extract to a sandboxed directory
51
+ - **wiki_origin** -- Resolve (and optionally fetch + verify) omitted originals
52
+ - **wiki_verify** -- CRC-32 / SHA-256 check of every entry
53
+
54
+ ### Pruned Archives (beta)
55
+ Store parts shared across Office documents (fonts, styles, themes, images) once, with the same `neozip-prune` library as `neozip prune` in NeoZip CLI. Documents are rebuilt byte-for-byte on extract. PDFs are stored whole for now (PDF pruning is not enabled yet). `extract`, `test`, `read_entry`, `grep_entries`, `info`, `list` and `zip://` handle pruned archives automatically (only when `META-INF/PRUNE.NZIP` is present).
56
+ - **prune_analyze** -- Report shared parts and prunable bytes (writes nothing)
57
+ - **prune_create** -- Create a verified pruned `.nzip` (`dryRun` to preview)
58
+ - **prune_info** -- Describe a pruned archive (`pruned: false` for regular archives)
59
+
41
60
  ### MCP Resources
42
61
  - **zip://** -- Direct access to archive manifests and entry contents as MCP resources
43
62
 
@@ -56,7 +75,7 @@ Account, identity, and recipient-key tools that talk to the NeoZip Token Service
56
75
  ### Blockchain Operations
57
76
  - **mint** -- Mint ZIP hash as NFT on Base network
58
77
  - **verify** -- Verify token authenticity against blockchain
59
- - **stamp** -- Submit ZIP merkle root to the NeoZip Token Service for timestamping
78
+ - **stamp** -- Submit ZIP merkle root to the NeoZip Token Service for timestamping (production origin requires Stripe membership via `neozip-connect membership`)
60
79
  - **upgrade_timestamped** -- Upgrade pending timestamp to confirmed (`META-INF/TIMESTAMP.NZIP`)
61
80
  - **wallet_info** -- View wallet and network status (address, balance)
62
81
 
@@ -75,7 +94,7 @@ The [npmjs.com package page](https://www.npmjs.com/package/neozip-mcp) shows **`
75
94
 
76
95
  | Command | Problem |
77
96
  |---------|---------|
78
- | `npm i neozip-mcp` | No **`@beta`** tag (version is on the `beta` dist-tag only) and no **`-g`** (CLI bins must be global) |
97
+ | `npm i neozip-mcp` | Missing **`-g`** (CLI bins must be global). Prefer `npm install -g neozip-mcp@0.9.5-beta` or `@latest` / `@beta`. |
79
98
  | `npm i neozip-mcp@beta` | Still local-only — `neozip-mcp` / `neozip-connect` won't be on your PATH for MCP hosts |
80
99
 
81
100
  **Use this:**
@@ -88,7 +107,7 @@ This package sets **`preferGlobal: true`**. MCP hosts (Claude Code, Cursor) spaw
88
107
 
89
108
  ### Prerequisites
90
109
 
91
- - Node.js 20.0.0 or higher
110
+ - Node.js 22.15.0 or higher (required for native zstd via Node zlib)
92
111
  - npm or pnpm
93
112
 
94
113
  ### Install from npm (beta)
@@ -199,7 +218,7 @@ Connection secrets use **machine-local encryption** in `~/.neozip/connection/`.
199
218
 
200
219
  | Variable | Default | Description |
201
220
  |----------|---------|-------------|
202
- | `NEOZIP_MCP_CAPABILITIES` | `auto` | Tool groups: `zip`, `blockchain`, `readonly`, `account`, or `auto` (default). `auto` → `zip,blockchain,readonly` when connect is `phase: ready` with a valid token; otherwise `zip,readonly` |
221
+ | `NEOZIP_MCP_CAPABILITIES` | `auto` | Tool groups: `zip`, `blockchain`, `readonly`, `account`, `wiki`, `prune`, or `auto` (default). `auto` → `zip,blockchain,readonly` when connect is `phase: ready` with a valid token; otherwise `zip,readonly` |
203
222
  | `NEOZIP_MCP_REQUIRE_ACCOUNT` | on when `account` or `blockchain` cap | Exit at startup if connection not `phase: ready` or token expired (`false` to disable) |
204
223
  | `NEOZIP_UNLOCK_PASSPHRASE` | machine-local key | Optional custom passphrase for `~/.neozip/connection/` (default: hostname + username on this machine) |
205
224
  | `NEOZIP_MCP_STARTUP_SUMMARY` | on | Log wallet/account summary to stderr on start |
@@ -214,8 +233,9 @@ Connection secrets use **machine-local encryption** in `~/.neozip/connection/`.
214
233
  | `NEOZIP_MCP_GREP_MAX_MATCHES` | `100` | Default max matches for `grep_entries` |
215
234
  | `NEOZIP_MCP_GREP_MAX_SNIPPET_CHARS` | `200` | Max snippet length per grep match |
216
235
  | `NEOZIP_MCP_GREP_MAX_FILE_BYTES` | `1048576` | Skip grepping entries larger than this (bytes) |
236
+ | `NEOZIP_MCP_WIKI_ALLOW_ORIGIN_FETCH` | off | Allow `wiki_origin` with `fetch: true` to download originals |
217
237
  | `NEOZIP_MCP_API_KEY` | -- | Optional API key for access control |
218
- | `NEOZIP_NETWORK` | `base-sepolia` | Blockchain network for tokenize/mint |
238
+ | `NEOZIP_NETWORK` | connection `defaultNetwork` (origin default) | Session override for tokenize/mint; clamped to the Token Service origin allowlist (testnet → Sepolia only; production → Mainnet only; local → both) |
219
239
  | `NEOZIP_TOKEN_SERVICE_INFO_URL` | `{profile URL}/info` | Link shown when Token Service setup is required |
220
240
  | `NEOZIP_IDENTITY_PRIVATE_KEY_HEX` | -- | Optional X25519 private key (hex) for opening recipient-encrypted archives (MCP env only) |
221
241
 
@@ -239,7 +259,7 @@ which neozip-mcp
239
259
 
240
260
  **`No matching version found`:**
241
261
 
242
- - The beta release is on the **`beta`** dist-tag. Install with `@beta` (or `@0.8.0-beta`).
262
+ - Install with `@latest`, `@beta`, or `@0.9.5-beta` (0.9.5-beta is published as the primary/`latest` version).
243
263
 
244
264
  ## Documentation
245
265
 
package/SECURITY.md CHANGED
@@ -22,7 +22,7 @@ ZIP format handling uses [neozipkit](https://www.npmjs.com/package/neozipkit). O
22
22
  ## General practices
23
23
 
24
24
  - **Dependencies** — Run `pnpm audit` (or `npm audit`) before release; address high/critical issues.
25
- - **Published tarball** — Recipient encryption code is bundled into `dist/vendor/neozipkit-pro.js` at build time; the published package does not require `@neowareinc/neozipkit-pro` at install time.
25
+ - **Published tarball** — Recipient encryption comes from the public `neozip-blockchain` dependency (`neozip-blockchain/encryption`); no private GitHub Packages package is required at install time.
26
26
  - **Inputs** — The server validates paths via `PathSandbox`; still avoid pointing sandbox paths at sensitive system directories unless required.
27
27
 
28
28
  ## Reporting a vulnerability
@@ -1,11 +1,9 @@
1
- import neozipkit from "neozipkit";
2
- const { HashCalculator } = neozipkit;
3
1
  import { TOKENIZED_METADATA, ZipkitVerifier } from "neozip-blockchain";
4
2
  import { findMetadataEntry, verifyTimestamp, verifyTimestampedZip, } from "neozip-blockchain/token-service";
5
3
  import { extractEntryToBuffer } from "./extract-entry-buffer.js";
6
- import { isMetadataEntryPath } from "./metadata-paths.js";
4
+ import { findTokenMetadataEntry } from "./metadata-paths.js";
7
5
  import { hasRecipientAccessMetadata } from "./recipient-access.js";
8
- import { computeMerkleRoot } from "./merkle.js";
6
+ import { computeMerkleRoot, matchDeclaredMerkleRoot } from "./merkle.js";
9
7
  import { enrichTimestampMetadata } from "./timestamp-network.js";
10
8
  import { ensureTokenServiceConfigured } from "../token-service/require-configured.js";
11
9
  export { isMetadataEntryPath } from "./metadata-paths.js";
@@ -42,8 +40,7 @@ export function formatBlockchainVerificationSummary(verification) {
42
40
  return "Blockchain verification check: PENDING";
43
41
  }
44
42
  export function detectArchiveKind(entries) {
45
- const hasToken = entries.some((e) => (e.fileName || e.filename) === TOKENIZED_METADATA);
46
- if (hasToken)
43
+ if (findTokenMetadataEntry(entries))
47
44
  return "tokenized";
48
45
  const metadata = findMetadataEntry(entries);
49
46
  if (metadata?.type === "confirmed")
@@ -61,7 +58,7 @@ function buildServiceOptions(config) {
61
58
  }
62
59
  export async function verifyArchiveBlockchain(zip, entries, config) {
63
60
  const kind = detectArchiveKind(entries);
64
- const merkleRoot = computeMerkleRoot(entries) ?? undefined;
61
+ const merkleRoot = (await computeMerkleRoot(zip)) ?? undefined;
65
62
  if (kind === "plain" || kind === "recipient-encrypted") {
66
63
  return {
67
64
  kind,
@@ -86,7 +83,7 @@ export async function verifyArchiveBlockchain(zip, entries, config) {
86
83
  }
87
84
  }
88
85
  if (kind === "tokenized") {
89
- const tokenEntry = entries.find((e) => (e.fileName || e.filename) === TOKENIZED_METADATA);
86
+ const tokenEntry = findTokenMetadataEntry(entries);
90
87
  if (!tokenEntry) {
91
88
  return {
92
89
  kind,
@@ -109,20 +106,12 @@ export async function verifyArchiveBlockchain(zip, entries, config) {
109
106
  merkleRoot,
110
107
  };
111
108
  }
112
- const hashCalc = new HashCalculator({ enableAccumulation: true });
113
- let hasHashes = false;
114
- for (const entry of entries) {
115
- const name = entry.fileName || entry.filename;
116
- if (name === TOKENIZED_METADATA || isMetadataEntryPath(name))
117
- continue;
118
- if (entry.sha256) {
119
- hashCalc.addHash(Buffer.from(entry.sha256, "hex"));
120
- hasHashes = true;
121
- }
122
- }
123
- const calculatedMerkleRoot = hasHashes
124
- ? hashCalc.merkleRoot()
109
+ const declared = metadataResult.metadata?.merkleRoot ||
110
+ merkleRoot;
111
+ const matched = declared
112
+ ? await matchDeclaredMerkleRoot(zip, declared)
125
113
  : null;
114
+ const calculatedMerkleRoot = matched?.root ?? merkleRoot ?? null;
126
115
  const verificationResult = await verifier.verifyToken(metadataResult.metadata, calculatedMerkleRoot, { debug: config.debug });
127
116
  const details = verificationResult.verificationDetails;
128
117
  const verified = Boolean(verificationResult.success);
@@ -77,13 +77,22 @@ export async function appendStoredEntries(sourcePath, outputPath, storedEntries)
77
77
  }
78
78
  async function loadArchiveMerkleRoot(archivePath) {
79
79
  const zip = new ZipkitNode();
80
- await zip.loadZipFile(archivePath);
81
- const entries = zip.getDirectory() || [];
82
- const merkleRoot = computeMerkleRoot(entries);
83
- if (!merkleRoot) {
84
- throw new Error("Archive has no SHA-256 hashes. Timestamped and tokenized archives require per-entry hashes.");
80
+ try {
81
+ await zip.loadZipFile(archivePath);
82
+ const merkleRoot = await computeMerkleRoot(zip);
83
+ if (!merkleRoot) {
84
+ throw new Error("Could not compute archive Merkle root (APPNOTE v1). Timestamped and tokenized archives require readable content entries.");
85
+ }
86
+ return merkleRoot;
87
+ }
88
+ finally {
89
+ try {
90
+ await zip.closeFile?.();
91
+ }
92
+ catch {
93
+ // ignore
94
+ }
85
95
  }
86
- return merkleRoot;
87
96
  }
88
97
  function buildTimestampOptions(config, options) {
89
98
  const timestampOptions = {};
@@ -214,15 +223,28 @@ export async function upgradeTimestampArchive(inputPath, outputPath, config, opt
214
223
  if (config.debug)
215
224
  serviceOptions.debug = true;
216
225
  const zip = new ZipkitNode();
217
- await zip.loadZipFile(inputPath);
218
- const entries = zip.getDirectory() || [];
219
- const metadataResult = findMetadataEntry(entries);
220
- if (!metadataResult) {
221
- throw new Error("No Token Service timestamp found in ZIP file.");
226
+ let metadata;
227
+ let metadataResult;
228
+ try {
229
+ await zip.loadZipFile(inputPath);
230
+ const entries = zip.getDirectory() || [];
231
+ metadataResult = findMetadataEntry(entries);
232
+ if (!metadataResult) {
233
+ throw new Error("No Token Service timestamp found in ZIP file.");
234
+ }
235
+ const loaded = await readTimestampMetadata(zip, metadataResult.entry);
236
+ if (!loaded) {
237
+ throw new Error("Failed to extract timestamp metadata.");
238
+ }
239
+ metadata = loaded;
222
240
  }
223
- const metadata = await readTimestampMetadata(zip, metadataResult.entry);
224
- if (!metadata) {
225
- throw new Error("Failed to extract timestamp metadata.");
241
+ finally {
242
+ try {
243
+ await zip.closeFile?.();
244
+ }
245
+ catch {
246
+ // ignore
247
+ }
226
248
  }
227
249
  if (!shouldUpgrade(metadata, metadataResult.type)) {
228
250
  throw new Error("Timestamp is already confirmed. No upgrade needed.");
@@ -1,5 +1,15 @@
1
1
  import { ZipkitNode } from "../neozipkit-node.js";
2
2
  import { extractEntryToBuffer } from "./extract-entry-buffer.js";
3
+ async function closeZipHandle(zip) {
4
+ try {
5
+ if (zip && typeof zip.closeFile === "function") {
6
+ await zip.closeFile();
7
+ }
8
+ }
9
+ catch {
10
+ // ignore
11
+ }
12
+ }
3
13
  /** Standard password for fixtures, smoke tests, and cursor scenarios (not for production). */
4
14
  export const FIXTURE_TEST_PASSWORD = "test-password";
5
15
  export const DEFAULT_PASSWORD_ENCRYPTION_METHOD = "neo-aes256";
@@ -120,6 +130,9 @@ export async function verifyEncryptedArchivePassword(archivePath, zipWithPasswor
120
130
  catch {
121
131
  // Expected when decryption requires a password
122
132
  }
133
+ finally {
134
+ await closeZipHandle(zipNoPassword);
135
+ }
123
136
  const zipWrongPassword = new ZipkitNode();
124
137
  await zipWrongPassword.loadZipFile(archivePath);
125
138
  applyArchivePassword(zipWrongPassword, `${password}-invalid`);
@@ -134,6 +147,9 @@ export async function verifyEncryptedArchivePassword(archivePath, zipWithPasswor
134
147
  catch {
135
148
  // Expected for wrong password
136
149
  }
150
+ finally {
151
+ await closeZipHandle(zipWrongPassword);
152
+ }
137
153
  return {
138
154
  encryptedEntryCount: encrypted.length,
139
155
  verified,
@@ -1,15 +1,34 @@
1
+ /**
2
+ * Extract a ZIP entry to a Buffer using neozipkit's file-based streaming API.
3
+ *
4
+ * neozipkit 1.0+ has no separate full-archive in-memory mode for Node.
5
+ * Use ZipkitNode.extractToBuffer() (chunked) — not core Zipkit.extract(),
6
+ * which only works for Buffer-loaded archives.
7
+ *
8
+ * Method 208 entries in pruned archives (META-INF/PRUNE.NZIP) are rebuilt by
9
+ * neozip-prune instead; neozipkit refuses that method.
10
+ */
11
+ import { PRUNE_ITEM_METHOD, getPruneContext, isPrunedEntry } from "../prune/detect.js";
12
+ import { readPrunedEntryToBuffer } from "../prune/read-entry.js";
13
+ /** In-memory rebuild cap for one pruned entry (read_entry / grep / resources). */
14
+ const PRUNED_ENTRY_MAX_BYTES = 256 * 1024 * 1024;
1
15
  export async function extractEntryToBuffer(zip, entry) {
16
+ const prune = getPruneContext(zip);
17
+ if (prune && entry.cmpMethod === PRUNE_ITEM_METHOD) {
18
+ throw new Error(`${entry.filename ?? entry.fileName} is a neozip-prune shared part (META-INF/PRUNE/ITEMS/), not a user file`);
19
+ }
20
+ if (prune && isPrunedEntry(entry)) {
21
+ return readPrunedEntryToBuffer(prune.archivePath, entry.filename ?? entry.fileName, Number(entry.uncompressedSize ?? 0), prune.manifest, PRUNED_ENTRY_MAX_BYTES);
22
+ }
2
23
  if (entry.cmpMethod === 0 &&
3
24
  (entry.realCmpMethod == null || entry.realCmpMethod < 0)) {
4
25
  entry.realCmpMethod = 0;
5
26
  }
6
- if (typeof zip.extractToBuffer === "function") {
7
- const buffer = await zip.extractToBuffer(entry);
8
- if (buffer && Buffer.isBuffer(buffer)) {
9
- return buffer;
10
- }
27
+ if (typeof zip.extractToBuffer !== "function") {
28
+ throw new Error("extractToBuffer is required for file-based archives (neozipkit streaming I/O). " +
29
+ "Buffer-only zip.extract() is not supported on ZipkitNode.loadZipFile().");
11
30
  }
12
- const buffer = await zip.extract(entry);
31
+ const buffer = await zip.extractToBuffer(entry);
13
32
  if (!buffer || !Buffer.isBuffer(buffer)) {
14
33
  throw new Error("Failed to extract entry");
15
34
  }
@@ -1,12 +1,17 @@
1
1
  import { detectTextSafety } from "./detect-text.js";
2
2
  import { getEntryEncryptionLabel, isEntryEncrypted } from "./encryption.js";
3
- function compressionMethodName(cmpMethod) {
3
+ import { PRUNE_ITEM_METHOD, PRUNE_METHOD } from "../prune/detect.js";
4
+ export function compressionMethodName(cmpMethod) {
4
5
  if (cmpMethod === 0)
5
6
  return "Stored";
6
7
  if (cmpMethod === 8)
7
8
  return "Deflate";
8
9
  if (cmpMethod === 93)
9
10
  return "Zstd";
11
+ if (cmpMethod === PRUNE_METHOD)
12
+ return "Prune";
13
+ if (cmpMethod === PRUNE_ITEM_METHOD)
14
+ return "PruneItem";
10
15
  return `Method ${cmpMethod}`;
11
16
  }
12
17
  export function buildEntrySummary(entry) {
@@ -1,31 +1,73 @@
1
- import neozipkit from "neozipkit";
2
- const { HashCalculator } = neozipkit;
3
- import { isMetadataEntryPath } from "./metadata-paths.js";
4
- export function computeMerkleRoot(entries) {
5
- let hasSHA256 = false;
1
+ /**
2
+ * Archive Merkle helpers (APPNOTE §6).
3
+ *
4
+ * New archives / stamp / mint: v1 via ZipkitNode.getMerkleRootAsync().
5
+ * Verify: matchMerkleRoot (v1 then v0). Do not use HashCalculator.merkleRoot()
6
+ * for archive roots — that path is neither APPNOTE v0 nor v1.
7
+ */
8
+ import { isMetaInfPath, matchMerkleRoot, } from "neozipkit";
9
+ import { getPruneContext } from "../prune/detect.js";
10
+ /** Preferred APPNOTE v1 content Merkle root for an open ZipkitNode archive. */
11
+ export async function computeMerkleRoot(zip) {
12
+ // v1 leaves hash rebuilt file content, which neozipkit cannot read for method 208.
13
+ if (getPruneContext(zip))
14
+ return null;
15
+ try {
16
+ if (typeof zip.getMerkleRootAsync === "function") {
17
+ return (await zip.getMerkleRootAsync()) ?? null;
18
+ }
19
+ return zip.getMerkleRoot?.() ?? null;
20
+ }
21
+ catch {
22
+ return null;
23
+ }
24
+ }
25
+ function collectMatchEntries(zip) {
26
+ const entries = zip.getDirectory?.() || [];
27
+ const result = [];
6
28
  for (const entry of entries) {
7
- const name = entry.fileName || entry.filename || "";
8
- if (isMetadataEntryPath(name))
29
+ const path = entry.filename || entry.fileName || "";
30
+ if (!path || entry.isDirectory || isMetaInfPath(path))
9
31
  continue;
10
- if (entry.sha256)
11
- hasSHA256 = true;
32
+ if (entry.merkleLeafV1 || entry.sha256) {
33
+ result.push({
34
+ path,
35
+ contentSha256: entry.sha256 || undefined,
36
+ merkleLeafV1: entry.merkleLeafV1 || undefined,
37
+ });
38
+ }
12
39
  }
13
- if (!hasSHA256)
40
+ return result;
41
+ }
42
+ /** APPNOTE §6.4: match a declared root (TOKEN.NZIP / TIMESTAMP) — v1 then v0. */
43
+ export async function matchDeclaredMerkleRoot(zip, declaredRoot) {
44
+ const expected = declaredRoot.toLowerCase().replace(/^0x/, "");
45
+ if (!/^[0-9a-f]{64}$/.test(expected))
14
46
  return null;
15
47
  try {
16
- const hashCalc = new HashCalculator({ enableAccumulation: true });
17
- for (const entry of entries) {
18
- const name = entry.fileName || entry.filename || "";
19
- if (isMetadataEntryPath(name))
20
- continue;
21
- if (entry.sha256) {
22
- hashCalc.addHash(Buffer.from(entry.sha256, "hex"));
23
- }
48
+ const v1 = await zip.getMerkleRootAsync?.({ algorithm: "v1" });
49
+ if (v1 && v1.toLowerCase() === expected) {
50
+ return { root: v1.toLowerCase(), algorithm: "v1", security: "high" };
24
51
  }
25
- return hashCalc.merkleRoot();
26
52
  }
27
53
  catch {
28
- return null;
54
+ // continue
55
+ }
56
+ try {
57
+ const v0 = zip.getMerkleRoot?.({ algorithm: "v0" });
58
+ if (v0 && v0.toLowerCase() === expected) {
59
+ return { root: v0.toLowerCase(), algorithm: "v0", security: "legacy" };
60
+ }
29
61
  }
62
+ catch {
63
+ // continue
64
+ }
65
+ const entries = collectMatchEntries(zip);
66
+ if (entries.length === 0)
67
+ return null;
68
+ const match = matchMerkleRoot(entries, declaredRoot);
69
+ if (!match)
70
+ return null;
71
+ return { ...match, root: expected };
30
72
  }
31
73
  //# sourceMappingURL=merkle.js.map
@@ -1,14 +1,30 @@
1
+ import { findReservedMetaEntry, isMetaInfPath, META_TOKEN_NZIP, META_TOKEN_NZIP_LEGACY, } from "neozipkit";
1
2
  import { TOKENIZED_METADATA } from "neozip-blockchain";
2
3
  import { ACCESS_NZIP_PATH } from "./recipient-access.js";
3
- const META_INF_PREFIX = "META-INF/";
4
- export function isMetadataEntryPath(entryPath) {
5
- const name = entryPath.replace(/\\/g, "/");
6
- return (name.startsWith(META_INF_PREFIX) ||
4
+ function entryPath(entryPathOrEntry) {
5
+ if (typeof entryPathOrEntry === "string") {
6
+ return entryPathOrEntry.replace(/\\/g, "/");
7
+ }
8
+ return (entryPathOrEntry.filename || entryPathOrEntry.fileName || "").replace(/\\/g, "/");
9
+ }
10
+ /** True for META-INF/** (ASCII case-insensitive) and reserved NeoZip sidecar names. */
11
+ export function isMetadataEntryPath(entryPathValue) {
12
+ const name = entryPath(entryPathValue);
13
+ return (isMetaInfPath(name) ||
7
14
  name === TOKENIZED_METADATA ||
8
- name === ACCESS_NZIP_PATH ||
9
- name.endsWith("/TOKEN.NZIP") ||
10
- name.endsWith("/TS-SUBMIT.NZIP") ||
11
- name.endsWith("/TIMESTAMP.NZIP") ||
12
- name.endsWith("/ACCESS.NZIP"));
15
+ name === ACCESS_NZIP_PATH);
16
+ }
17
+ /** ASCII case-insensitive TOKEN.NZIP / legacy NZIP.TOKEN discovery. */
18
+ export function findTokenMetadataEntry(entries) {
19
+ const wrapped = entries.map((entry) => ({
20
+ filename: entryPath(entry),
21
+ entry,
22
+ }));
23
+ const found = findReservedMetaEntry(wrapped, [
24
+ META_TOKEN_NZIP,
25
+ META_TOKEN_NZIP_LEGACY,
26
+ TOKENIZED_METADATA,
27
+ ]);
28
+ return found?.entry;
13
29
  }
14
30
  //# sourceMappingURL=metadata-paths.js.map
@@ -0,0 +1,49 @@
1
+ /**
2
+ * Native zstd (Node zlib) requirements for neozip-mcp.
3
+ * neozipkit 1.0+ removed WASM zstd; Node streaming uses zlib.createZstd*.
4
+ */
5
+ import * as zlib from "node:zlib";
6
+ const MIN_MAJOR = 22;
7
+ const MIN_MINOR = 15;
8
+ export function parseNodeVersion(version = process.version) {
9
+ const m = /^v(\d+)\.(\d+)\.(\d+)/.exec(version);
10
+ if (!m) {
11
+ return { major: 0, minor: 0, patch: 0 };
12
+ }
13
+ return { major: Number(m[1]), minor: Number(m[2]), patch: Number(m[3]) };
14
+ }
15
+ /** True when Node zlib exposes createZstdCompress / createZstdDecompress. */
16
+ export function isNativeZstdRuntimeAvailable() {
17
+ return (typeof zlib.createZstdCompress ===
18
+ "function" &&
19
+ typeof zlib.createZstdDecompress ===
20
+ "function");
21
+ }
22
+ export function nodeSupportsNativeZstd(version = process.version) {
23
+ const { major, minor } = parseNodeVersion(version);
24
+ if (major > MIN_MAJOR)
25
+ return true;
26
+ if (major === MIN_MAJOR && minor >= MIN_MINOR)
27
+ return true;
28
+ return isNativeZstdRuntimeAvailable();
29
+ }
30
+ export function assertNativeZstdAvailable(context) {
31
+ if (nodeSupportsNativeZstd()) {
32
+ return;
33
+ }
34
+ throw new Error(`${context} requires Node.js >= ${MIN_MAJOR}.${MIN_MINOR} ` +
35
+ `(with zlib.createZstdCompress / createZstdDecompress). Current: ${process.version}. ` +
36
+ `Upgrade Node, or use method "deflate" / "store".`);
37
+ }
38
+ /** ZIP method 93 (zstd), including under WinZip AES method 99. */
39
+ export function entryUsesZstd(entry) {
40
+ const method = entry.cmpMethod === 99 && (entry.realCmpMethod ?? -1) >= 0
41
+ ? entry.realCmpMethod
42
+ : entry.cmpMethod;
43
+ return method === 93;
44
+ }
45
+ export function archiveHasZstdEntries(entries) {
46
+ return entries.some(entryUsesZstd);
47
+ }
48
+ export const NATIVE_ZSTD_MIN_NODE = `${MIN_MAJOR}.${MIN_MINOR}`;
49
+ //# sourceMappingURL=native-zstd.js.map
@@ -1,18 +1,36 @@
1
1
  import { ZipkitNode } from "../neozipkit-node.js";
2
2
  import { applyArchivePassword } from "./encryption.js";
3
3
  import { applyRecipientDecryptIfNeeded } from "./recipient-decrypt.js";
4
+ import { archiveHasZstdEntries, assertNativeZstdAvailable, } from "./native-zstd.js";
5
+ import { registerPruneContext } from "../prune/detect.js";
6
+ /** Close the ZipkitNode read handle (avoids Node DEP0137 FileHandle GC warnings). */
7
+ export async function closeArchive(zip) {
8
+ try {
9
+ if (zip && typeof zip.closeFile === "function") {
10
+ await zip.closeFile();
11
+ }
12
+ }
13
+ catch {
14
+ // ignore close errors
15
+ }
16
+ }
4
17
  export async function openArchive(input, sandbox, resourceLimiter, config, options) {
5
18
  const archivePath = await sandbox.validatePath(input);
6
19
  await resourceLimiter.checkFileSize(archivePath);
20
+ // Always file-based load (chunked streaming; no in-memory archive mode).
7
21
  const zip = new ZipkitNode();
8
22
  await zip.loadZipFile(archivePath);
9
23
  let entries = zip.getDirectory() || [];
10
24
  resourceLimiter.checkEntryCount(entries.length);
25
+ if (archiveHasZstdEntries(entries)) {
26
+ assertNativeZstdAvailable("Reading zstd-compressed archives");
27
+ }
11
28
  const recipientResult = await applyRecipientDecryptIfNeeded(zip, archivePath, entries, config, options);
12
29
  if (!recipientResult.decrypted) {
13
30
  applyArchivePassword(zip, options?.password);
14
31
  }
15
32
  entries = zip.getDirectory() || [];
33
+ registerPruneContext(zip, archivePath, entries);
16
34
  return {
17
35
  archivePath,
18
36
  zip,
@@ -20,4 +38,14 @@ export async function openArchive(input, sandbox, resourceLimiter, config, optio
20
38
  recipientDecrypted: recipientResult.decrypted,
21
39
  };
22
40
  }
41
+ /** Open an archive, run work, then always close the file handle. */
42
+ export async function withOpenArchive(input, sandbox, resourceLimiter, config, options, fn) {
43
+ const result = await openArchive(input, sandbox, resourceLimiter, config, options);
44
+ try {
45
+ return await fn(result);
46
+ }
47
+ finally {
48
+ await closeArchive(result.zip);
49
+ }
50
+ }
23
51
  //# sourceMappingURL=open-archive.js.map