neozip-cli 0.90.0 → 0.95.0

package/dist/src/cli/schema.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * Machine-readable schema introspection.
+ *
+ * Unlike a REST CLI with a Discovery document, NeoZip's commands are described
+ * by a hand-authored registry. `neozip schema <command>` emits the accepted
+ * `--params` fields, the `--json` payload shape, output shape, and exit codes so
+ * an agent can construct calls without scraping `--help`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getCommandSchema = getCommandSchema;
+exports.listSchemaCommands = listSchemaCommands;
+exports.handleSchemaCommand = handleSchemaCommand;
+const NEOZIP_SCHEMA = {
+    command: 'neozip',
+    summary: 'Create or update an archive, optionally with blockchain tokenization.',
+    output: 'Human text by default. Pass --format json for a structured result. --dry-run previews without writing.',
+    params: [
+        { name: 'level', type: 'number', description: 'Compression level 0-9 (0=store).', default: 6, legacySafe: true },
+        { name: 'compression', type: 'string', enum: ['zstd', 'deflate'], description: 'Compression algorithm.', default: 'zstd', legacySafe: false },
+        { name: 'legacy', type: 'boolean', description: 'Produce an InfoZip/PKZIP-compatible archive (forces deflate/store + PKZIP, disables NeoZip extensions).', default: false, legacySafe: true },
+        { name: 'encrypt', type: 'boolean', description: 'Encrypt entries (prompts for password unless password is given).', default: false, legacySafe: true },
+        { name: 'password', type: 'string', description: 'Encryption password. Use with care (visible in process list).', legacySafe: true },
+        { name: 'encryptionMethod', type: 'string', enum: ['aes256', 'pkzip'], description: 'Encryption method. --legacy forces pkzip.', default: 'aes256', legacySafe: false },
+        { name: 'blockchain', type: 'boolean', description: 'Enable blockchain tokenization. Incompatible with legacy.', default: false, legacySafe: false },
+        { name: 'blockchainOts', type: 'boolean', description: 'Add an OpenTimestamps (Bitcoin) proof. Incompatible with legacy.', default: false, legacySafe: false },
+        { name: 'blockchainTokenService', type: 'boolean', description: 'Add a Token Service timestamp (requires neozip connect). Incompatible with legacy.', default: false, legacySafe: false },
+        { name: 'network', type: 'string', description: 'Blockchain network name (e.g. base-sepolia).', default: 'base-sepolia', legacySafe: false },
+        { name: 'recurse', type: 'boolean', description: 'Recurse into directories.', default: false, legacySafe: true },
+        { name: 'junkPaths', type: 'boolean', description: 'Store only file names, not directory paths.', default: false, legacySafe: true },
+        { name: 'include', type: 'string[]', description: 'Glob patterns to include.', legacySafe: true },
+        { name: 'exclude', type: 'string[]', description: 'Glob patterns to exclude.', legacySafe: true },
+        { name: 'inMemory', type: 'boolean', description: 'Use in-memory compression.', default: false, legacySafe: true },
+        { name: 'testIntegrity', type: 'boolean', description: 'Test the archive after creation.', default: false, legacySafe: true },
+        { name: 'verbose', type: 'boolean', description: 'Verbose output.', default: false, legacySafe: true },
+        { name: 'quiet', type: 'boolean', description: 'Suppress output.', default: false, legacySafe: true },
+    ],
+    payload: [
+        { name: 'archive', type: 'string', description: 'Output archive path (positional arg 1).' },
+        { name: 'files', type: 'string[]', description: 'Files/directories to add (positional args 2+).' },
+        { name: 'include', type: 'string[]', description: 'Glob patterns to include.' },
+        { name: 'exclude', type: 'string[]', description: 'Glob patterns to exclude.' },
+    ],
+    exitCodes: [
+        { code: 0, meaning: 'Success' },
+        { code: 10, meaning: 'Parameter error' },
+        { code: 15, meaning: "Can't write archive" },
+        { code: 18, meaning: "Can't find archive" },
+        { code: 26, meaning: 'Blockchain configuration error' },
+    ],
+    notes: [
+        'Output format is selected with --format json (not --json). --json supplies the payload.',
+        'Example: neozip --format json --params \'{"level":9,"legacy":true}\' --json \'{"files":["a.txt","dir/"]}\' out.zip',
+    ],
+};
+const NEOUNZIP_SCHEMA = {
+    command: 'neounzip',
+    summary: 'Extract, test, or list an archive.',
+    output: 'Human text by default. Pass --format json for a structured result. --dry-run previews the extraction plan.',
+    params: [
+        { name: 'exdir', type: 'string', description: 'Extraction directory (zip-slip validated).' },
+        { name: 'overwrite', type: 'boolean', description: 'Overwrite existing files.', default: false },
+        { name: 'never', type: 'boolean', description: 'Never overwrite existing files.', default: false },
+        { name: 'junkPaths', type: 'boolean', description: 'Strip directory paths on extraction.', default: false },
+        { name: 'testOnly', type: 'boolean', description: 'Test archive integrity only.', default: false },
+        { name: 'listOnly', type: 'boolean', description: 'List archive contents only.', default: false },
+        { name: 'preVerify', type: 'boolean', description: 'Verify integrity/blockchain before extracting.', default: false },
+        { name: 'password', type: 'string', description: 'Decryption password.' },
+        { name: 'include', type: 'string[]', description: 'Glob patterns to include.' },
+        { name: 'exclude', type: 'string[]', description: 'Glob patterns to exclude.' },
+        { name: 'skipBlockchain', type: 'boolean', description: 'Skip blockchain verification.', default: false },
+        { name: 'inMemory', type: 'boolean', description: 'Use in-memory processing.', default: false },
+        { name: 'verbose', type: 'boolean', description: 'Verbose output.', default: false },
+        { name: 'quiet', type: 'boolean', description: 'Suppress output.', default: false },
+    ],
+    payload: [
+        { name: 'archive', type: 'string', description: 'Archive path (positional arg 1).' },
+        { name: 'exdir', type: 'string', description: 'Extraction directory (positional arg 2 or exdir).' },
+        { name: 'filePatterns', type: 'string[]', description: 'Entry name patterns to extract (positional args 3+).' },
+    ],
+    exitCodes: [
+        { code: 0, meaning: 'Success' },
+        { code: 1, meaning: 'Warning (completed with issues)' },
+        { code: 9, meaning: 'Files not found' },
+        { code: 10, meaning: 'Invalid options' },
+        { code: 82, meaning: 'Bad password' },
+    ],
+    notes: [
+        'Extraction refuses entries that escape the target directory (zip-slip protection).',
+        'Example: neounzip --format json --params \'{"exdir":"out","overwrite":true}\' archive.zip',
+    ],
+};
+const NEOLIST_SCHEMA = {
+    command: 'neolist',
+    summary: 'List the contents of an archive.',
+    output: 'Human text by default. Pass --format json (or the legacy -j/--json) for JSON.',
+    params: [
+        { name: 'sortBy', type: 'string', enum: ['name', 'size', 'date'], description: 'Sort order.' },
+        { name: 'include', type: 'string[]', description: 'Glob patterns to include.' },
+        { name: 'exclude', type: 'string[]', description: 'Glob patterns to exclude.' },
+        { name: 'noComments', type: 'boolean', description: 'Suppress comments.', default: false },
+        { name: 'inMemory', type: 'boolean', description: 'Use in-memory processing.', default: false },
+        { name: 'verbose', type: 'boolean', description: 'Verbose output.', default: false },
+    ],
+    exitCodes: [
+        { code: 0, meaning: 'Success' },
+        { code: 9, meaning: 'Files not found' },
+        { code: 10, meaning: 'Invalid options' },
+        { code: 82, meaning: 'Password-protected (cannot list)' },
+    ],
+    notes: ['Example: neolist --format json archive.zip'],
+};
+const CONNECT_SCHEMA = {
+    command: 'connect',
+    summary: 'Token Service account + wallet setup. Shares ~/.neozip/connection/ with NeoZip Desktop and MCP.',
+    output: 'Pass --json on any subcommand for a structured ConnectCliResult.',
+    params: [
+        { name: 'email', type: 'string', description: 'Account email for register/verify.' },
+        { name: 'code', type: 'string', description: 'Verification code.' },
+        { name: 'phone', type: 'string', description: 'E.164 phone number for phone verification.' },
+        { name: 'connectionId', type: 'string', description: 'Target a specific connection.' },
+        { name: 'tokenServiceUrl', type: 'string', description: 'Override the Token Service URL.' },
+        { name: 'label', type: 'string', description: 'Friendly label for the connection.' },
+        { name: 'network', type: 'string', description: 'Network name for connect fund (e.g. base-sepolia).' },
+        { name: 'chain', type: 'number', description: 'Chain id for connect fund (overrides --network).' },
+    ],
+    exitCodes: [
+        { code: 0, meaning: 'Success' },
+        { code: 12, meaning: 'Command failed' },
+    ],
+    notes: [
+        'Subcommands: status, register, verify, refresh, fund, phone, wallet, finish, select, rename, dump, settings, migrate, logout, delete, reset.',
+        'connect refresh renews an expired access token (silent wallet-signature login, else email OTP).',
+        'connect fund [request|status|policy] requests native gas for the Data Wallet from the Token Service funding API.',
+        'Non-interactive subcommands accept --json for structured output. The bare wizard requires a TTY.',
+    ],
+};
+const REGISTRY = {
+    neozip: NEOZIP_SCHEMA,
+    zip: NEOZIP_SCHEMA,
+    neounzip: NEOUNZIP_SCHEMA,
+    unzip: NEOUNZIP_SCHEMA,
+    neolist: NEOLIST_SCHEMA,
+    list: NEOLIST_SCHEMA,
+    connect: CONNECT_SCHEMA,
+};
+/** Look up a command schema by name (case-insensitive, with aliases). */
+function getCommandSchema(command) {
+    return REGISTRY[command.toLowerCase()];
+}
+/** List the canonical introspectable command names. */
+function listSchemaCommands() {
+    return ['neozip', 'neounzip', 'neolist', 'connect'];
+}
+/**
+ * Handle `neozip schema [command]`. Prints JSON to stdout. Returns the process
+ * exit code (0 on success, 10 on a bad command name).
+ */
+function handleSchemaCommand(args) {
+    const target = args[0];
+    if (!target) {
+        // No command given: emit an index of available commands.
+        const index = {
+            ok: true,
+            commands: listSchemaCommands(),
+            usage: 'neozip schema <neozip|neounzip|neolist|connect>',
+        };
+        process.stdout.write(JSON.stringify(index, null, 2) + '\n');
+        return 0;
+    }
+    const schema = getCommandSchema(target);
+    if (!schema) {
+        process.stdout.write(JSON.stringify({
+            ok: false,
+            error: {
+                code: 'UNKNOWN_COMMAND',
+                message: `Unknown command "${target}"`,
+                commands: listSchemaCommands(),
+            },
+        }, null, 2) + '\n');
+        return 10;
+    }
+    process.stdout.write(JSON.stringify({ ok: true, schema }, null, 2) + '\n');
+    return 0;
+}
+//# sourceMappingURL=schema.js.map

package/dist/src/cli/validate.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Input hardening for agent-driven (and adversarial) input.
+ *
+ * Agents hallucinate. Treat all CLI/JSON-supplied strings as untrusted:
+ *  - Reject control characters and dangerous Unicode (zero-width, bidi
+ *    overrides) that can hide intent in file names and paths.
+ *  - Prevent zip-slip: extracted entries must resolve inside the target dir.
+ *
+ * Adapted from the patterns in the Google Workspace CLI `validate.rs`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = void 0;
+exports.rejectControlChars = rejectControlChars;
+exports.assertSafeArchiveName = assertSafeArchiveName;
+exports.validateSafeOutputDir = validateSafeOutputDir;
+exports.resolveSafeExtractPath = resolveSafeExtractPath;
+const path = __importStar(require("path"));
+/** Raised when input fails a hardening check. */
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+exports.ValidationError = ValidationError;
+// C0 controls (0x00-0x1F), DEL (0x7F), and C1 controls (0x80-0x9F).
+const CONTROL_CHARS = /[\u0000-\u001F\u007F-\u009F]/;
+// Zero-width and bidirectional-override characters that can disguise paths.
+const DANGEROUS_UNICODE = /[\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u206F\uFEFF]/;
+/**
+ * Reject control characters and dangerous Unicode in a value. Returns the value
+ * unchanged when it is safe.
+ */
+function rejectControlChars(value, label) {
+    if (CONTROL_CHARS.test(value)) {
+        throw new ValidationError(`${label} contains control characters`);
+    }
+    if (DANGEROUS_UNICODE.test(value)) {
+        throw new ValidationError(`${label} contains disallowed Unicode characters`);
+    }
+    return value;
+}
+/**
+ * Validate an archive name / file path for control characters. Does not enforce
+ * a sandbox (archives may legitimately live anywhere the user can write).
+ */
+function assertSafeArchiveName(name) {
+    return rejectControlChars(name, 'Archive name');
+}
+/**
+ * Validate an output directory string. Rejects control chars and returns the
+ * resolved absolute path.
+ */
+function validateSafeOutputDir(dir, label = 'Output directory') {
+    rejectControlChars(dir, label);
+    return path.resolve(dir);
+}
+/**
+ * Resolve an archive entry name against a target extraction directory and ensure
+ * the result stays inside that directory (zip-slip protection).
+ *
+ * - Rejects control characters / dangerous Unicode in the entry name.
+ * - Rejects absolute entry paths.
+ * - Rejects `..` traversal that escapes the target directory.
+ *
+ * Returns the safe absolute destination path for the entry.
+ */
+function resolveSafeExtractPath(targetDir, entryName) {
+    rejectControlChars(entryName, `Entry "${entryName}"`);
+    // Normalize Windows separators so checks are consistent cross-platform.
+    const normalizedEntry = entryName.replace(/\\/g, '/');
+    if (path.isAbsolute(normalizedEntry) || /^[A-Za-z]:[\\/]/.test(normalizedEntry)) {
+        throw new ValidationError(`Entry "${entryName}" uses an absolute path (refusing to extract)`);
+    }
+    const resolvedTarget = path.resolve(targetDir);
+    const destination = path.resolve(resolvedTarget, normalizedEntry);
+    const withSep = resolvedTarget.endsWith(path.sep)
+        ? resolvedTarget
+        : resolvedTarget + path.sep;
+    if (destination !== resolvedTarget && !destination.startsWith(withSep)) {
+        throw new ValidationError(`Entry "${entryName}" escapes the extraction directory (path traversal)`);
+    }
+    return destination;
+}
+//# sourceMappingURL=validate.js.map

package/dist/src/commands/mintTimestampProof.js

@@ -48,9 +48,11 @@ const os = __importStar(require("os"));
 const ethers_1 = require("ethers");
 const node_1 = __importDefault(require("neozipkit/node"));
 const node_2 = require("neozipkit/node");
-const zipstamp_server_1 = require("neozip-blockchain/zipstamp-server");
+const token_service_1 = require("neozip-blockchain/token-service");
 const neozip_blockchain_1 = require("neozip-blockchain");
-const blockchain_1 = require("../neozip/blockchain");
+const cli_guidance_1 = require("../connection/cli-guidance");
+const funding_1 = require("../connection/funding");
+const bootstrap_1 = require("../connection/bootstrap");
 const RPC_BY_CHAIN = {
     84532: 'https://sepolia.base.org',
     421614: 'https://sepolia-rollup.arbitrum.io/rpc',
@@ -78,27 +80,34 @@ function getErrorMessage(error) {
  */
 async function runMintTimestampProof(options) {
     const { inputPath, outputPath, walletKey: cliWalletKey, debug = false } = options;
+    const walletGuidance = (0, cli_guidance_1.requireConnectionReady)('On-chain mint', 'wallet');
+    if (walletGuidance) {
+        console.error(walletGuidance);
+        return false;
+    }
     if (!fs.existsSync(inputPath)) {
         console.error(`Error: ZIP file not found: ${inputPath}`);
         return false;
     }
-    const walletKey = (0, blockchain_1.getWalletPasskey)(cliWalletKey, true);
+    const creds = (0, bootstrap_1.readCliConnectionCredentials)();
+    const walletKey = cliWalletKey || creds.walletKey;
     if (!walletKey) {
+        console.error('Error: No wallet key in connection store. Run: neozip connect');
         return false;
     }
     const zip = new node_1.default();
     await zip.loadZipFile(inputPath);
     const entries = zip.getDirectory() || [];
-    const metadataResult = (0, zipstamp_server_1.findMetadataEntry)(entries);
+    const metadataResult = (0, token_service_1.findMetadataEntry)(entries);
     if (!metadataResult) {
-        console.error('No Zipstamp timestamp found in ZIP file');
+        console.error('No Token Service timestamp found in ZIP file');
         return false;
     }
     if (metadataResult.type !== 'confirmed') {
         console.error('Archive must have confirmed timestamp (TIMESTAMP.NZIP). Run "neozip upgrade <archive>" first.');
         return false;
     }
-    let timestampMetadata = await (0, zipstamp_server_1.extractTimestampData)(zip, metadataResult.entry);
+    let timestampMetadata = await (0, token_service_1.extractTimestampData)(zip, metadataResult.entry);
     if (!timestampMetadata || !timestampMetadata.digest) {
         // Fallback for file-based ZIPs where zip.extract() may not work
         try {
@@ -123,14 +132,16 @@ async function runMintTimestampProof(options) {
     }
     const chainId = timestampMetadata.chainId ?? 84532;
     const batchId = timestampMetadata.batchId ?? undefined;
+    const serverUrl = (0, bootstrap_1.resolveVerifyServerUrl)(timestampMetadata.serverUrl);
+    const tsOpts = { debug, serverUrl };
     console.log('Checking NFT status...');
-    const nftStatus = await (0, zipstamp_server_1.checkNFTStatus)(timestampMetadata.digest, chainId, { debug });
+    const nftStatus = await (0, token_service_1.checkNFTStatus)(timestampMetadata.digest, chainId, tsOpts);
     if (nftStatus.isMinted && nftStatus.tokenId) {
         console.log(`Digest already minted as token #${nftStatus.tokenId}`);
         console.log('Proceeding to create TOKEN.NZIP with existing token data...');
     }
     console.log('Preparing mint data...');
-    const prepareResult = await (0, zipstamp_server_1.prepareMint)(timestampMetadata.digest, chainId, batchId, { debug });
+    const prepareResult = await (0, token_service_1.prepareMint)(timestampMetadata.digest, chainId, batchId, tsOpts);
     if (!prepareResult.success || !prepareResult.mintData) {
         console.error(`Error: ${prepareResult.error || 'Failed to prepare mint data'}`);
         return false;
@@ -159,6 +170,7 @@ async function runMintTimestampProof(options) {
         const mintFeeWei = BigInt(mintData.mintFeeWei);
         if (balance < mintFeeWei) {
             console.error(`Error: Insufficient balance. Required: ${mintData.mintFee} ETH`);
+            console.error(`   ${(0, funding_1.formatLowBalanceFundingHint)()}`);
             return false;
         }
         const nftContract = new ethers_1.ethers.Contract(mintData.nftContractAddress, neozip_blockchain_1.NZIP_CONTRACT_ABI_V250, wallet);
@@ -197,14 +209,14 @@ async function runMintTimestampProof(options) {
                 let existingTokenId;
                 let existingOwner;
                 let existingBlockNumber;
-                const existingStatus = await (0, zipstamp_server_1.checkNFTStatus)(timestampMetadata.digest, chainId, { debug });
+                const existingStatus = await (0, token_service_1.checkNFTStatus)(timestampMetadata.digest, chainId, tsOpts);
                 if (existingStatus.isMinted && existingStatus.tokenId) {
                     existingTokenId = existingStatus.tokenId;
                     existingOwner = existingStatus.owner;
                     existingBlockNumber = existingStatus.proofData?.batchBlockNumber;
                 }
                 if (!existingTokenId) {
-                    const verifyRes = await (0, zipstamp_server_1.verifyDigest)(timestampMetadata.digest, chainId, batchId ?? undefined, undefined, { debug });
+                    const verifyRes = await (0, token_service_1.verifyDigest)(timestampMetadata.digest, chainId, batchId ?? undefined, undefined, tsOpts);
                     if (verifyRes.verified && verifyRes.tokenId) {
                         existingTokenId = verifyRes.tokenId;
                         existingOwner = verifyRes.owner;
@@ -219,7 +231,7 @@ async function runMintTimestampProof(options) {
                     console.log(`Using existing token #${tokenId}. Creating TOKEN.NZIP...`);
                 }
                 else {
-                    console.error('Mint failed: digest is already minted on-chain but token details could not be retrieved. Try the Zipstamp server or block explorer for this digest.');
+                    console.error('Mint failed: digest is already minted on-chain but token details could not be retrieved. Try the Token Service or block explorer for this digest.');
                     console.error(`Details: ${msg}`);
                     return false;
                 }
@@ -251,10 +263,10 @@ async function runMintTimestampProof(options) {
             batchTimestamp: mintData.batchTimestamp,
             registryAddress: mintData.registryAddress,
             nftContractAddress: mintData.nftContractAddress,
-            serverUrl: (0, zipstamp_server_1.getZipStampServerUrl)(),
+            serverUrl: serverUrl ?? '',
         },
     };
-    const metadataFiles = (0, zipstamp_server_1.getMetadataFileNames)();
+    const metadataFiles = (0, token_service_1.getMetadataFileNames)();
     const outPath = outputPath ?? inputPath.replace(/(\.nzip|\.zip)$/i, '-nft$1');
     const tempDir = path.dirname(outPath) || '.';
     const tempPath = path.join(tempDir, `.neozip-mint-${Date.now()}.tmp`);
@@ -286,7 +298,7 @@ async function runMintTimestampProof(options) {
         zipCopy.writeCentralDirectoryAndEOCD(destPath, allEntries, { zipComment: '' });
         fs.renameSync(destPath, outPath);
         console.log(`Output: ${outPath}`);
-        // Summary matching Zipstamp verification style
+        // Summary matching Token Service verification style
         console.log('\n🔗 Mint complete:');
         console.log(' - Status: ✅ MINTED');
         console.log(' - Stamp type: NZIP-NFT (tokenized archive)');