neozipkit 0.1.1

package/examples/zip-token.ts

@@ -0,0 +1,604 @@
+#!/usr/bin/env node
+
+// ======================================
+//	NeoZip.ts
+//  A command-line utility for creating and managing ZIP archives using NeoZipKit
+//  Copyright (c) 2025 NeoWare, Inc. All rights reserved.
+// ======================================
+
+import * as readline from 'readline';
+import { exit, off } from 'process';
+import { ZipKitServer, NEOZIPKIT_INFO } from 'neozipkit';
+import type { CompressOptions } from 'neozipkit';
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { NEOZIP_VERSION, NEOZIP_RELEASE_DATE } from './version';
+import * as path from 'path';
+import * as fs from 'fs';
+import * as crc32 from 'crc-32';
+
+// Import blockchain components
+import { ZipTokenProcessor, MintingOptions, queryBlockchainForExistingToken } from './blockchain';
+import { TOKENIZED_METADATA } from '../src/constants/Headers';
+
+// Display copyright and version header on startup
+console.log(`NeoZip v${NEOZIP_VERSION} (${NEOZIP_RELEASE_DATE})  Copyright (c) 2025 NeoWare, Inc. All rights reserved`);
+console.log(`Using NeoZipKit v${NEOZIPKIT_INFO.version} (${NEOZIPKIT_INFO.releaseDate})`);
+
+// NFT Metadata template
+const NFT_METADATA_TEMPLATE = {
+  name: "NeoZip Archive Token",
+  description: "This NFT represents ownership of a timestamped and verified ZIP archive on Base",
+  image: "", // Will be set to IPFS hash of thumbnail
+  attributes: [
+    {
+      trait_type: "Archive Hash",
+      value: "" // Will be set to the Merkle root hash of the archive
+    },
+    {
+      trait_type: "Creation Date",
+      value: "" // Will be set to timestamp
+    },
+    {
+      trait_type: "Blockchain",
+      value: "Base" // Specify Base as the blockchain
+    }
+  ]
+};
+
+/**
+ * Command line argument parser configuration using yargs.
+ * Supports the following options:
+ * -r/--recurse: Recurse into directories
+ * -m/--move: Move files into archive after adding
+ * -u/--update: Add new or update existing entries if source is newer
+ * -e/--encrypt: Encrypt entries using password protection
+ * -f/--freshen: Update only existing entries
+ * -i/--include: Include only specified files
+ * -x/--exclude: Exclude specified files
+ * -z/--zipComment: Add archive comment
+ * -L/--license: Show license information
+ * -H/--SHA-256: Calculate SHA-256 hash for entries
+ * -S/--timestamp: Submit timestamp to Bitcoin blockchain
+ * -Z/--zipcomp: Use Zip compatible compression (deflate) instead of Zstandard
+ * -0/--store: Store files without compression
+ * -1...-9: Set compression level (1=fastest, 9=highest compression, 6=default)
+ */
+const options = yargs(hideBin(process.argv))
+ .usage("Usage: $0 <zipfile> <files to add...>")
+ .demandCommand(1, "Error - The .zip filename is required.")
+ .option('r', { alias: 'recurse', describe: 'Recurse into directories', type: 'boolean' })
+ .option('m', { alias: 'move', describe: 'Move specified files into the zip archive', type: 'boolean' })
+ .option('u', { alias: 'update', describe: 'Add new entries/update existing entries only if source is newer', type: 'boolean' })
+ .option('e', { alias: 'encrypt', describe: 'Encrypt entries in a zip archive', type: 'boolean' })
+ .option('f', { alias: 'freshen', describe: 'Update existing entries only (no new entries added)', type: 'boolean' })
+ .option('x', { alias: 'exclude', describe: 'Exclude the specified files', type: 'array' })
+ .option('L', { alias: 'license', describe: 'Display software license', type: 'boolean' })
+ .option('H', { alias: 'SHA-256', describe: 'Calculate SHA-256 Hash on entries', type: 'boolean' })
+ //  .option('S', { alias: 'timestamp', describe: 'Submit Timestamp to Bitcoin blockchain', type: 'boolean' })
+ .option('Z', { alias: 'zipcomp', describe: 'Use Zip compatible compression (deflate) instead of Zstandard', type: 'boolean', default: false })
+ .option('0', {
+   alias: 'store',
+   type: 'boolean',
+   description: 'Store files without compression',
+   default: false
+ })
+ // Add individual compression level shortcuts
+ .option('1', { type: 'boolean', hidden: true })
+ .option('2', { type: 'boolean', hidden: true })
+ .option('3', { type: 'boolean', hidden: true })
+ .option('4', { type: 'boolean', hidden: true })
+ .option('5', { type: 'boolean', hidden: true })
+ .option('6', { type: 'boolean', hidden: true })
+ .option('7', { type: 'boolean', hidden: true })
+ .option('8', { type: 'boolean', hidden: true })
+ .option('9', { type: 'boolean', hidden: true })
+ .option('l', { alias: 'list', describe: 'List archive files (short format)', type: 'boolean' })
+ // Add blockchain wallet options
+ .option('wallet', { describe: 'Path to wallet key file or mnemonic phrase', type: 'string' })
+ .option('network', { describe: 'Base network to connect to', type: 'string', default: 'base-sepolia' })
+ .option('skip-blockchain', { describe: 'Skip blockchain operations and create regular ZIP file', type: 'boolean' })
+ .option('y', { alias: 'yes', describe: 'Automatically confirm NFT token creation without prompting', type: 'boolean' })
+ .help('help', 'Show help').alias('help', 'h')
+ .wrap(null)
+ .group(['r', 'm', 'd', 'e', 'f', 'i', 'j', 'x', 'z', 'L', 'H', 'S', 'Z', '0'], 'Options:')
+ .group(['wallet', 'network', 'skip-blockchain', 'y'], 'Blockchain Options:')
+ .epilog('-1...-9: Compression levels: -1 (fastest) to -9 (maximum compression), -6 (default)\n\nCopyright (c) 2025 NeoWare, Inc. - Type "neozip "-L" for software license.')
+ .parseSync();
+
+const zipKit = new ZipKitServer();
+
+const zipFile = options._[0] as string;
+zipKit.loadZipFile(zipFile);
+
+if (options.L) {
+  console.log('Copyright (c) 2025 by NeoWare, Inc.  All rights reserved\n');
+  exit(0);
+}
+
+const filesAdded = zipKit.addFiles(options._.slice(1) as string[], options.f, options.u);
+if (filesAdded === 0) {
+  console.error("Error: No files specified to add to archive.");
+  exit(1);
+}
+console.log('filesAdded', filesAdded);
+processZip();
+
+/**
+ * Determines the compression level from command line options
+ * @returns number representing the compression level (0-9)
+ */
+function getCompressionLevel(): number {
+  if (options.store) return 0;
+  
+  // Check for individual compression level flags (-1 through -9)
+  for (let i = 1; i <= 9; i++) {
+    if (options[i.toString()]) {
+      return i;
+    }
+  }
+  
+  // Default compression level
+  return 6;
+}
+
+/**
+ * Validates compression options for conflicts
+ * @returns boolean indicating if the options are valid
+ */
+function validateCompressionOptions(): boolean {
+  // Count how many individual compression level options are set
+  let levelCount = 0;
+  for (let i = 1; i <= 9; i++) {
+    if (options[i.toString()]) {
+      levelCount++;
+    }
+  }
+  
+  // Check if more than one individual compression level is specified
+  if (levelCount > 1) {
+    console.error('Error: Cannot specify more than one compression level (-1 through -9)');
+    return false;
+  }
+  
+  // Check if both store (0) and compression level options are specified
+  if (options.store && levelCount > 0) {
+    console.error('Error: Cannot specify both -0/--store and compression level options');
+    return false;
+  }
+  
+  return true;
+}
+
+/**
+ * Sets the compression options for the ZIP archive
+ * @returns Promise resolving to the compression options
+ */
+async function setCompressionOptions(): Promise<CompressOptions> {
+  // Validate compression options
+  if (!validateCompressionOptions()) {
+    exit(1);
+  }
+
+  // Display compression information
+  if (options.store) {
+    console.log('Using storage mode (no compression)');
+  } else {
+    const compressionLevel = getCompressionLevel();
+    const compressionMethod = options.Z ? 'Deflate (zip-compatible)' : 'ZStandard';
+    console.log(`Using ${compressionMethod} compression algorithm with level ${compressionLevel}`);
+  }
+
+  // Input password
+  let _password = null;
+  if (options.e) {
+    _password = await inputPassword('Enter password: ');
+    const _verify = await inputPassword('Verify password: ');
+    if (_password != _verify) {
+      console.log('Zip Error: Password verification failed');
+      exit(1);
+    }
+  }
+  
+  const compressOptions: CompressOptions = {
+    level: getCompressionLevel(),
+    password: options.e && _password ? _password : undefined,
+    useSHA256: options.H,
+    useZstd: !options.Z // Use Zstandard by default, disable when -Z is specified
+  };
+  console.log('compressOptions', compressOptions);
+
+  return compressOptions;
+}
+
+/**
+ * Outputs the final ZIP archive file and handles blockchain operations
+ */
+async function processZip() {
+  // Set compression options
+  const compressOptions = await setCompressionOptions();
+  
+  // Use our new createZipToken function that properly processes files first,
+  // then calculates merkle root, then handles blockchain operations
+  await createZipToken(zipFile, compressOptions);
+}
+
+/**
+ * Prompts the user for a password with optional verification
+ * @param question - The prompt message to display
+ * @returns Promise resolving to the entered password
+ */
+async function inputPassword(question: string): Promise<string> {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    terminal: true
+  });
+
+  return new Promise<string>((resolve) => {
+    rl.question(question, (input: string) => {
+      rl.close();
+      resolve(input);
+    });
+  });
+}
+
+/**
+ * Creates a ZIP file with NFT token metadata
+ * 
+ * This method creates a ZIP file with NFT token metadata, which includes
+ * blockchain token information for the ZIP file's contents.
+ * 
+ * @param zipFile - The path to the ZIP file to create
+ * @param compressOptions - The compression options for the ZIP file
+ * @returns void - Creates the ZIP file with embedded token metadata
+ */
+async function createZipToken(zipFile: string, compressOptions: CompressOptions) {
+  
+  // Ensure the directory structure for the output file exists
+  const outputDir = path.dirname(zipFile);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Generate a unique temporary file name in the output directory
+  const _tempZipFile = path.join(outputDir, `neozip-${Date.now()}.zip`);
+
+  // Open or create the .zip file for writing
+  const fd = fs.openSync(_tempZipFile, 'w');
+
+  console.log('Processing files and calculating hashes...');
+  
+  // Remove any existing token metadata entries from the ZIP directory BEFORE processing
+  console.log('🔧 Scanning ZIP directory for existing token files...');
+  const currentZipEntries = zipKit.getDirectory();
+  if (currentZipEntries) {
+    const existingTokenEntries = currentZipEntries.filter((entry: any) => entry.filename === TOKENIZED_METADATA);
+    if (existingTokenEntries.length > 0) {
+      console.log(`   Found ${existingTokenEntries.length} existing token metadata entries - removing them`);
+      // Remove existing token entries
+      for (const existingEntry of existingTokenEntries) {
+        const index = currentZipEntries.indexOf(existingEntry);
+        if (index > -1) {
+          currentZipEntries.splice(index, 1);
+          console.log(`   ❌ Removed: ${existingEntry.filename}`);
+        }
+      }
+      console.log(`   ✅ Successfully removed ${existingTokenEntries.length} existing token entries`);
+    } else {
+      console.log('   ✅ No existing token entries found in ZIP directory');
+    }
+  }
+  
+  // Process all files and calculate SHA256 hashes - this populates the Central Directory
+  let offset = await zipKit.createZipFileData(compressOptions, {
+    onReadEntryData: (entry: any) => {
+      try {
+        return fs.readFileSync(entry.filename);
+      } catch (error) {
+        throw new Error(`Failed to read file: ${entry.filename}`);
+      }
+    },
+    onOutputBuffer: (buffer: Buffer) => {
+      fs.writeSync(fd, buffer);
+    },
+    onEntryDone: (entry: any, status: string) => {
+      console.log(`${status} ${entry.filename} to ${zipFile}`);
+    } 
+  });
+
+  // NOW we can get the merkle root since files have been processed
+  const _merkleRoot = zipKit.getMerkleRoot();
+
+  // Exit immediately if merkle root is null
+  if (!_merkleRoot) {
+    fs.closeSync(fd);
+    fs.unlinkSync(_tempZipFile);
+    console.error('Error: Merkle root is null after processing files.');
+    console.log('This typically means insufficient files or missing -H flag for SHA256 calculation.');
+    exit(1);
+  }
+
+  console.log('\nMerkle Root: ' + _merkleRoot);
+
+  // Check for existing token inside the ZIP file and compare merkle roots
+  let existingTokenMetadata = null;
+  let shouldReuseExistingToken = false;
+  
+  // Check if the ZIP file already exists and contains a token
+  if (fs.existsSync(zipFile)) {
+    console.log('\n🔍 Checking existing ZIP file for token metadata...');
+    
+    try {
+      // Load the existing ZIP file to check for token
+      const existingZipKit = new ZipKitServer();
+      const existingZipData = fs.readFileSync(zipFile);
+      existingZipKit.loadZip(existingZipData);
+      
+      // Look for existing token entry
+      const existingEntries = existingZipKit.getDirectory();
+      const existingTokenEntry = existingEntries?.find((entry: any) => entry.filename === TOKENIZED_METADATA);
+      
+      if (existingTokenEntry) {
+        console.log('📋 Found existing token in ZIP file');
+        
+        // Extract and parse the existing token
+        const tokenBuffer = await existingZipKit.extract(existingTokenEntry);
+        if (tokenBuffer) {
+          const tokenContent = tokenBuffer.toString('utf8');
+          existingTokenMetadata = JSON.parse(tokenContent);
+          
+          console.log('\n🔍 Existing token detected:');
+          console.log('═'.repeat(60));
+          console.log(`Token ID: ${existingTokenMetadata.tokenId}`);
+          console.log(`Contract: ${existingTokenMetadata.contractAddress}`);
+          console.log(`Network: ${existingTokenMetadata.network}`);
+          console.log(`Merkle Root: ${existingTokenMetadata.merkleRoot}`);
+          console.log(`File Name: ${existingTokenMetadata.fileName}`);
+          console.log(`Minted At: ${existingTokenMetadata.mintedAt}`);
+          console.log('═'.repeat(60));
+          
+          // Compare merkle roots
+          console.log('\n🔍 Comparing calculated merkle root with existing token...');
+          console.log(`Calculated: ${_merkleRoot}`);
+          console.log(`Existing:   ${existingTokenMetadata.merkleRoot}`);
+          
+          if (_merkleRoot === existingTokenMetadata.merkleRoot) {
+            console.log('✅ Merkle roots match! The content hasn\'t changed.');
+            
+            if (!options.skipBlockchain && !options.y) {
+              console.log('\n🤔 What would you like to do?');
+              console.log('═'.repeat(60));
+              console.log('1. Keep existing token (recommended for unchanged content)');
+              console.log('2. Create new token with current timestamp');
+              console.log('═'.repeat(60));
+              
+              const userChoice = await inputPassword('Enter your choice (1-2): ');
+              if (userChoice.trim() === '1') {
+                shouldReuseExistingToken = true;
+                console.log('✅ Keeping existing token metadata');
+              } else {
+                console.log('✅ Will create new token with current timestamp');
+              }
+            } else if (options.y) {
+              // Auto-mode: default to keeping existing token for unchanged content
+              shouldReuseExistingToken = true;
+              console.log('✅ Auto-mode: Keeping existing token for unchanged content');
+            }
+          } else {
+            console.log('⚠️  Merkle roots differ! The content has been modified.');
+            console.log('   A new token will be created for the updated content.');
+          }
+        }
+      } else {
+        console.log('✅ No existing token found in ZIP file');
+      }
+      
+    } catch (error) {
+      console.warn(`   ⚠️  Could not read existing ZIP file: ${error}`);
+      existingTokenMetadata = null;
+    }
+  } else {
+    console.log('✅ Creating new ZIP file (no existing file found)');
+  }
+
+  // Handle blockchain operations
+  let tokenMetadataEntry = null;
+  let userCancelledMinting = false;
+
+  if (!options.skipBlockchain) {
+    if (shouldReuseExistingToken && existingTokenMetadata) {
+      // Reuse existing token - no blockchain operations needed
+      console.log('\n♻️  Reusing existing token metadata...');
+      
+      // Create the token content from existing metadata
+      const tokenContent = JSON.stringify(existingTokenMetadata, null, 2);
+      console.log('\n📄 Existing token metadata content:');
+      console.log('═'.repeat(60));
+      console.log(tokenContent);
+      console.log('═'.repeat(60));
+      
+      // Create a ZipEntry for the token metadata (virtual file in ZIP)
+      const tokenEntry = zipKit.createZipEntry('META-INF/NZIP.TOKEN');
+      const tokenBuffer = Buffer.from(tokenContent, 'utf8');
+      
+      tokenEntry.timeDateDOS = tokenEntry.setDateTime(new Date());
+      tokenEntry.compressedSize = tokenBuffer.length;
+      tokenEntry.uncompressedSize = tokenBuffer.length;
+      tokenEntry.cmpMethod = 0; // STORED
+      tokenEntry.crc = (crc32.buf(tokenBuffer) >>> 0); // Convert to unsigned 32-bit integer
+      tokenEntry.fileBuffer = tokenBuffer;
+      tokenEntry.platform = process.platform;
+      
+      // Ensure this entry is marked for inclusion
+      tokenEntry.isUpdated = true;
+      
+      tokenMetadataEntry = tokenEntry;
+      console.log('✅ Existing token metadata prepared for ZIP inclusion!');
+      
+    } else {
+      // Need to create new token - ask user for confirmation
+      console.log('\n🎉 ZIP archive ready for tokenization!');
+      console.log('📋 This will mint an NFT token representing this archive on the Base blockchain.');
+      console.log('💰 Blockchain operations may require gas fees (small network transaction costs).');
+      
+      let confirmed = false;
+      if (options.y || options.yes) {
+        console.log('✅ Auto-confirming blockchain operations (--yes flag)');
+        confirmed = true;
+      } else {
+        const userConfirmed = await inputPassword('Proceed with blockchain operations? (y/n): ');
+        confirmed = userConfirmed.toLowerCase().trim() === 'y' || userConfirmed.toLowerCase().trim() === 'yes';
+      }
+      
+      if (!confirmed) {
+        console.log('❌ Blockchain operations cancelled by user.');
+        userCancelledMinting = true;
+      } else {
+      console.log('✅ Proceeding with NFT token minting...');
+        
+        const mintingOptions: MintingOptions = {
+          wallet: options.wallet,
+          network: options.network,
+          mintToken: true
+        };
+
+      try {
+        console.log('\nInitializing blockchain components...');
+        const processor = new ZipTokenProcessor(zipFile, _merkleRoot, mintingOptions);
+        const state = await processor.processZipToken(mintingOptions);
+
+        if (state.error) {
+          console.error('\nBlockchain processing failed:', state.error);
+          
+          // All blockchain errors should result in cancellation - no token reuse
+          userCancelledMinting = true;
+        } else {
+          console.log('\nBlockchain processing completed successfully!');
+          
+          if (state.walletSetup) {
+            console.log(`Wallet: ${state.walletSetup.wallet?.address}`);
+          }
+          
+          if (state.mintingResult) {
+            console.log(`Token minting: ${state.mintingResult.success ? 'Success' : 'Failed'}`);
+            if (!state.mintingResult.success) {
+              if (state.mintingResult.message.includes('already tokenized by another wallet')) {
+                console.log('\n⚠️  This ZIP content has already been tokenized by someone else!');
+                console.log(`ℹ️  ${state.mintingResult.message}`);
+                userCancelledMinting = true;
+              } else {
+                console.error(`Token minting failed: ${state.mintingResult.message}`);
+                userCancelledMinting = true;
+              }
+            } else {
+              // New token minted successfully
+              
+              if (state.mintingResult.tokenId) {
+                console.log(`Token ID: ${state.mintingResult.tokenId}`);
+                console.log(`Transaction: ${state.mintingResult.txHash}`);
+              }
+              console.log(`Message: ${state.mintingResult.message}`);
+
+              // Create token metadata entry if we have valid token info
+              if (state.tokenInfo && state.mintingResult.tokenId && state.mintingResult.txHash) {
+                console.log('\nCreating META-INF/NZIP.TOKEN entry...');
+                
+                // Create the token content
+                const tokenContent = JSON.stringify(state.tokenInfo, null, 2);
+                console.log('\n📄 Token metadata content:');
+                console.log('═'.repeat(60));
+                console.log(tokenContent);
+                console.log('═'.repeat(60));
+                
+                // Create a ZipEntry for the token metadata (virtual file in ZIP)
+                const tokenEntry = zipKit.createZipEntry('META-INF/NZIP.TOKEN');
+                const tokenBuffer = Buffer.from(tokenContent, 'utf8');
+                
+                tokenEntry.timeDateDOS = tokenEntry.setDateTime(new Date());
+                tokenEntry.compressedSize = tokenBuffer.length;
+                tokenEntry.uncompressedSize = tokenBuffer.length;
+                tokenEntry.cmpMethod = 0; // STORED
+                tokenEntry.crc = (crc32.buf(tokenBuffer) >>> 0); // Convert to unsigned 32-bit integer
+                tokenEntry.fileBuffer = tokenBuffer;
+                tokenEntry.platform = process.platform;
+                
+                // Ensure this entry is marked for inclusion
+                tokenEntry.isUpdated = true;
+                
+                tokenMetadataEntry = tokenEntry;
+                console.log('✅ Token metadata entry created for ZIP inclusion!');
+              } else {
+                console.error('ERROR: Token minting completed but no valid token metadata was created.');
+                userCancelledMinting = true;
+              }
+            }
+          }
+        }
+      } catch (error) {
+        console.error('\nError in blockchain processing:', error);
+        userCancelledMinting = true;
+      }
+      }
+    }
+  }
+
+  
+
+  // Finish the ZIP file with or without token metadata
+  if (tokenMetadataEntry) {
+    console.log('\n🔧 Adding new token metadata to ZIP archive...');
+    console.log(`   Entry: ${tokenMetadataEntry.filename}`);
+    console.log(`   Size: ${tokenMetadataEntry.uncompressedSize} bytes`);
+  }
+  
+  await zipKit.finishZipFileData(
+    offset, 
+    function onOutputBuffer(buffer: Buffer) {
+      fs.writeSync(fd, buffer);
+    },
+    tokenMetadataEntry || undefined
+  );
+
+  // Close the ZIP file
+  fs.closeSync(fd);
+  
+  // Delete the existing ZIP file if it exists
+  if (fs.existsSync(zipFile)) {
+    fs.unlinkSync(zipFile);
+  }
+
+  // Replace with the new ZIP file
+  fs.renameSync(_tempZipFile, zipFile);
+
+  // Report final results
+  if (tokenMetadataEntry) {
+    console.log('\n🎉 ZIP file created successfully with embedded NFT token metadata!');
+    console.log('✅ The archive contains its blockchain identity in META-INF/NZIP.TOKEN');
+    console.log('🔒 Full blockchain verification is now possible with this tokenized archive');
+  } else if (userCancelledMinting) {
+    console.log('\n📦 ZIP file created successfully (non-tokenized).');
+    console.log('❌ BLOCKCHAIN TOKEN RETRIEVAL FAILED');
+    console.log('💡 Actual error details should be shown above in the blockchain processing section');
+    console.log('🔧 Common issues:');
+    console.log('   - RPC endpoint connectivity problems');
+    console.log('   - Blockchain network congestion');
+    console.log('   - Token exists but cannot be queried due to network issues');
+    console.log('💡 Only archives with full NFT token metadata support blockchain verification');
+  } else if (options.skipBlockchain) {
+    console.log('\n📦 ZIP file created successfully (non-tokenized).');
+    console.log('ℹ️  Blockchain operations were skipped. Remove --skip-blockchain to mint NFT tokens.');
+  } else {
+    console.log('\n📦 ZIP file created successfully (non-tokenized).');
+    console.log('⚠️  Token operations failed - check error messages above');
+  }
+
+  // Show final archive contents
+  console.log('\nFinal archive contents:');
+  const zipEntries = zipKit.getDirectory();
+  if (zipEntries) {
+    zipEntries.forEach((entry: any) => {
+      console.log(`  ${entry.filename}`);
+    });
+  }
+}