neozipkit 0.2.1 → 0.3.0

package/examples/blockchain-tokenize.ts

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+
+/**
+ * Blockchain Tokenization Example
+ * 
+ * Demonstrates creating a tokenized ZIP file with blockchain NFT minting.
+ * This is a minimal example showing the basic tokenization flow.
+ * 
+ * SECURITY WARNING:
+ * - NEVER use mainnet private keys in examples
+ * - ONLY use testnet keys with minimal test funds
+ * - NEVER commit private keys to version control
+ * - Store private keys in .env file (excluded from git)
+ * - Rotate keys immediately if accidentally exposed
+ * - Wallet files (wallet/neozip-wallet.json) are automatically excluded from git
+ * 
+ * See SECURITY.md for complete security guidelines.
+ * 
+ * Note: This example requires:
+ * - A wallet private key with testnet ETH
+ * - Network configuration (defaults to Base Sepolia testnet)
+ * - Gas fees for minting
+ */
+
+import { ZipkitNode } from '../src/node';
+import { ZipkitMinter } from '../src/blockchain/core/ZipkitMinter';
+import type { CompressOptions } from '../src/core';
+import type { TokenMetadata } from '../src/types';
+import { TOKENIZED_METADATA } from '../src/core/constants/Headers';
+import { crc32 } from '../src/core/encryption/ZipCrypto';
+import * as fs from 'fs';
+import * as path from 'path';
+import dotenv from 'dotenv';
+
+// Load .env.local first (local overrides), then .env
+dotenv.config({ path: '.env.local' });
+dotenv.config(); // Loads .env if .env.local doesn't exist
+
+async function main() {
+  console.log('Blockchain Tokenization Example\n');
+
+  // Check for wallet private key
+  const walletPrivateKey = process.env.NEOZIP_WALLET_PASSKEY;
+  if (!walletPrivateKey) {
+    console.error('❌ Error: NEOZIP_WALLET_PASSKEY environment variable is required');
+    console.error('   Please set your wallet private key:');
+    console.error('   export NEOZIP_WALLET_PASSKEY="0x..."');
+    console.error('\n💡 Get testnet ETH from:');
+    console.error('   https://www.coinbase.com/faucets/base-ethereum-sepolia-faucet');
+    process.exit(1);
+  }
+
+  // Network configuration (default to Base Sepolia testnet)
+  const network = process.env.NEOZIP_NETWORK || 'base-sepolia';
+
+  // Create some test files
+  const testFiles: string[] = [];
+  const testDir = path.join(__dirname, 'test-files');
+  
+  if (!fs.existsSync(testDir)) {
+    fs.mkdirSync(testDir, { recursive: true });
+  }
+
+  const file1 = path.join(testDir, 'document.txt');
+  const file2 = path.join(testDir, 'data.json');
+
+  if (!fs.existsSync(file1)) {
+    fs.writeFileSync(file1, 'This is a sample document.\nIt will be tokenized on the blockchain.');
+  }
+  testFiles.push(file1);
+
+  if (!fs.existsSync(file2)) {
+    fs.writeFileSync(file2, JSON.stringify({ name: 'Sample Data', value: 12345 }, null, 2));
+  }
+  testFiles.push(file2);
+
+  console.log('Source files:');
+  testFiles.forEach(file => {
+    const stats = fs.statSync(file);
+    console.log(`  - ${path.basename(file)} (${stats.size} bytes)`);
+  });
+  console.log();
+
+  // Create ZipkitNode instance
+  const zip = new ZipkitNode();
+
+  // Define output ZIP file path
+  const outputZip = path.join(__dirname, 'output', 'tokenized.zip');
+  const outputDir = path.dirname(outputZip);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Compression options with SHA-256 enabled (required for merkle root calculation)
+  const options: CompressOptions = {
+    level: 6,
+    useZstd: true,
+    useSHA256: true  // IMPORTANT: Enable SHA-256 for blockchain features
+  };
+
+  try {
+    console.log('Step 1: Creating ZIP archive with SHA-256 hashes...');
+    
+    // Create ZIP file from files
+    await zip.createZipFromFiles(testFiles, outputZip, options);
+
+    console.log(`✅ ZIP archive created: ${outputZip}\n`);
+
+    // Load the ZIP to get entries and calculate merkle root
+    console.log('Step 2: Calculating merkle root...');
+    await zip.loadZipFile(outputZip);
+    
+    // Get merkle root (this requires SHA-256 hashes to be calculated)
+    const merkleRoot = (zip as any).getMerkleRoot?.();
+    
+    if (!merkleRoot) {
+      console.error('❌ Error: Could not calculate merkle root');
+      console.error('   Make sure useSHA256: true is set in compression options');
+      await zip.closeFile(); // Close file handle before exiting
+      process.exit(1);
+    }
+
+    console.log(`✅ Merkle root calculated: ${merkleRoot}\n`);
+
+    // Close file handle to prevent warnings
+    await zip.closeFile();
+
+    // Initialize blockchain minter
+    console.log('Step 3: Initializing blockchain minter...');
+    const minter = new ZipkitMinter(merkleRoot, {
+      walletPrivateKey: walletPrivateKey,
+      network: network,
+      verbose: true,
+      debug: false
+    });
+
+    // Get wallet information
+    const walletInfo = await minter.getWalletInfo();
+    console.log(`✅ Wallet: ${walletInfo.address}`);
+    console.log(`   Balance: ${walletInfo.balance} ETH`);
+    console.log(`   Network: ${walletInfo.networkName}\n`);
+
+    // Check for existing tokens
+    console.log('Step 4: Checking for existing tokens...');
+    const duplicateCheck = await minter.checkForDuplicates();
+    
+    if (duplicateCheck.hasExistingTokens) {
+      console.log(`⚠️  Found ${duplicateCheck.allTokens.length} existing token(s) with this merkle root:`);
+      duplicateCheck.userOwnedTokens.forEach(token => {
+        console.log(`   - Token ID ${token.tokenId} (owned by you)`);
+      });
+      duplicateCheck.othersTokens.forEach(token => {
+        console.log(`   - Token ID ${token.tokenId} (owned by others)`);
+      });
+      console.log('\n💡 This example will proceed with minting a new token.');
+      console.log('   In a real application, you might want to use an existing token instead.\n');
+    } else {
+      console.log('✅ No existing tokens found. Proceeding with new mint.\n');
+    }
+
+    // Estimate gas costs
+    console.log('Step 5: Estimating gas costs...');
+    const gasCosts = await minter.estimateGasCosts();
+    console.log(`   Estimated gas cost: ${gasCosts.estimatedCost} ETH\n`);
+
+    // Mint the token
+    console.log('Step 6: Minting NFT token on blockchain...');
+    console.log('   This will incur gas costs. Please wait...\n');
+    
+    const mintResult = await minter.mintToken();
+
+    if (mintResult.success) {
+      console.log(`✅ Token minted successfully!`);
+      console.log(`   Token ID: ${mintResult.tokenId}`);
+      console.log(`   Transaction: ${mintResult.transactionHash}`);
+      console.log(`   Contract: ${mintResult.contractAddress}`);
+      if (mintResult.gasUsed) {
+        console.log(`   Gas Used: ${mintResult.gasUsed}`);
+      }
+      if (mintResult.gasCost) {
+        console.log(`   Gas Cost: ${mintResult.gasCost} ETH`);
+      }
+      console.log();
+
+      // Step 7: Add token metadata to ZIP file
+      console.log('Step 7: Adding token metadata to ZIP file...');
+      
+      // Create token metadata object
+      const tokenMetadata: TokenMetadata = {
+        version: '1.0',
+        tokenId: mintResult.tokenId!,
+        contractAddress: mintResult.contractAddress!,
+        network: walletInfo.networkName,
+        networkChainId: walletInfo.networkName === 'Base Sepolia' ? 84532 : undefined,
+        transactionHash: mintResult.transactionHash,
+        merkleRoot: merkleRoot,
+        mintedAt: new Date().toISOString(),
+        mintDate: new Date().toISOString()
+      };
+
+      // Rebuild ZIP with token metadata
+      await addTokenMetadataToZip(zip, outputZip, tokenMetadata, testFiles, options);
+
+      console.log(`✅ Token metadata added to ZIP file`);
+      console.log(`   Metadata file: ${TOKENIZED_METADATA}`);
+      console.log();
+      console.log(`📄 View token on explorer:`);
+      const explorerUrl = `https://sepolia.basescan.org/token/${mintResult.contractAddress}?a=${mintResult.tokenId}`;
+      console.log(`   ${explorerUrl}`);
+      
+      // Explicitly exit to prevent hanging
+      process.exit(0);
+
+    } else {
+      console.error(`❌ Token minting failed: ${mintResult.message}`);
+      process.exit(1);
+    }
+
+  } catch (error) {
+    console.error('❌ Error during tokenization:');
+    console.error(error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    }
+    // Ensure file handle is closed on error
+    try {
+      await zip.closeFile();
+    } catch (closeError) {
+      // Ignore close errors
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Add token metadata to ZIP file by rebuilding it with the metadata entry
+ */
+async function addTokenMetadataToZip(
+  zip: ZipkitNode,
+  zipPath: string,
+  tokenMetadata: TokenMetadata,
+  originalFiles: string[],
+  options: CompressOptions
+): Promise<void> {
+  // Create token metadata content
+  const tokenContent = JSON.stringify(tokenMetadata, null, 2);
+  const tokenBuffer = Buffer.from(tokenContent, 'utf8');
+
+  // Create temporary ZIP file
+  const tempZipPath = zipPath + '.tmp';
+  
+  // Create a fresh ZipkitNode instance for the new ZIP
+  const newZip = new ZipkitNode();
+  
+  // Initialize new ZIP file
+  const writer = await newZip.initializeZipFile(tempZipPath);
+
+  try {
+    // Add all original files
+    for (const filePath of originalFiles) {
+      const entry = await newZip.prepareEntryFromFile(filePath);
+      await newZip.writeZipEntry(writer, entry, filePath, options);
+    }
+
+    // Add token metadata entry (STORED, uncompressed)
+    const tokenEntry = newZip.createZipEntry(TOKENIZED_METADATA);
+    tokenEntry.timeDateDOS = tokenEntry.setDateTime(new Date());
+    tokenEntry.uncompressedSize = tokenBuffer.length;
+    tokenEntry.compressedSize = tokenBuffer.length;
+    tokenEntry.cmpMethod = 0; // STORED (no compression)
+    tokenEntry.crc = crc32(tokenBuffer);
+    tokenEntry.fileBuffer = tokenBuffer;
+    
+    // Add entry to ZIP entries list
+    newZip.getDirectory().push(tokenEntry);
+    
+    // Write token entry manually (STORED method)
+    tokenEntry.localHdrOffset = writer.currentPosition;
+    writer.entryPositions.set(TOKENIZED_METADATA, tokenEntry.localHdrOffset);
+    const localHeader = tokenEntry.createLocalHdr();
+    
+    await new Promise<void>((resolve, reject) => {
+      writer.outputStream.write(localHeader, (error) => {
+        if (error) {
+          reject(error);
+        } else {
+          writer.currentPosition += localHeader.length;
+          resolve();
+        }
+      });
+    });
+
+    // Write token data
+    await new Promise<void>((resolve, reject) => {
+      writer.outputStream.write(tokenBuffer, (error) => {
+        if (error) {
+          reject(error);
+        } else {
+          writer.currentPosition += tokenBuffer.length;
+          resolve();
+        }
+      });
+    });
+
+    // Get all entries (including token metadata)
+    const allEntries = newZip.getDirectory();
+
+    // Write central directory
+    const centralDirOffset = writer.currentPosition;
+    const centralDirSize = await newZip.writeCentralDirectory(writer, allEntries);
+
+    // Write EOCD
+    await newZip.writeEndOfCentralDirectory(
+      writer,
+      allEntries.length,
+      centralDirSize,
+      centralDirOffset
+    );
+
+    // Finalize and close
+    await newZip.finalizeZipFile(writer);
+
+    // Wait a moment for file system to sync
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+    // Replace original ZIP with new one
+    if (fs.existsSync(zipPath)) {
+      fs.unlinkSync(zipPath);
+    }
+    fs.renameSync(tempZipPath, zipPath);
+
+    // Ensure file handles are released
+    await new Promise(resolve => setTimeout(resolve, 100));
+
+  } catch (error) {
+    // Clean up temp file on error
+    if (fs.existsSync(tempZipPath)) {
+      try {
+        fs.unlinkSync(tempZipPath);
+      } catch (unlinkError) {
+        // Ignore unlink errors
+      }
+    }
+    throw error;
+  }
+}
+
+// Run the example
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+

package/examples/create-zip.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+/**
+ * Create ZIP Example
+ * 
+ * Demonstrates creating a ZIP archive from multiple files using ZipkitNode.
+ * This is a minimal example showing the basic API usage.
+ */
+
+import ZipkitNode from '../src/node';
+import type { CompressOptions } from '../src/core';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Helper function to format bytes
+ */
+function formatBytes(bytes: number): string {
+  if (bytes === 0) return '0 B';
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return (bytes / Math.pow(k, i)).toFixed(1) + ' ' + sizes[i];
+}
+
+/**
+ * Helper function to pad string to the right
+ */
+function padRight(str: string, length: number): string {
+  return (str + ' '.repeat(length)).slice(0, length);
+}
+
+/**
+ * Helper function to pad string to the left
+ */
+function padLeft(str: string, length: number): string {
+  return (' '.repeat(length) + str).slice(-length);
+}
+
+async function main() {
+  console.log('Creating ZIP archive example...\n');
+
+  // Test files to compress (located in test-files directory)
+  const testDir = path.join(__dirname, 'test-files');
+  const testFiles = [
+    path.join(testDir, 'file1.txt'),
+    path.join(testDir, 'file2.txt'),
+    path.join(testDir, 'document.md'),
+    path.join(testDir, 'data.json')
+  ];
+
+  // Verify all test files exist
+  for (const file of testFiles) {
+    if (!fs.existsSync(file)) {
+      console.error(`❌ Error: Test file not found: ${file}`);
+      console.error('   Make sure test-files directory contains the required files.');
+      process.exit(1);
+    }
+  }
+
+  console.log('Source files:');
+  testFiles.forEach(file => {
+    const stats = fs.statSync(file);
+    console.log(`  - ${path.basename(file)} (${stats.size} bytes)`);
+  });
+  console.log();
+
+  // Create ZipkitNode instance
+  const zip = new ZipkitNode();
+
+  // Define output ZIP file path
+  const outputZip = path.join(__dirname, 'output', 'example.zip');
+
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputZip);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Compression options
+  const options: CompressOptions = {
+    level: 6,        // Compression level (0-9, higher = better compression but slower)
+    useZstd: false,  // Use Deflate compression (standard ZIP)
+    useSHA256: false // Don't calculate SHA-256 hashes (faster, but needed for blockchain features)
+  };
+
+  try {
+    console.log('Creating ZIP archive...');
+    
+    // Method 1: Simple API - create ZIP from file paths
+    // This is the easiest way to create a ZIP file
+    await zip.createZipFromFiles(testFiles, outputZip, options);
+
+    console.log(`✅ ZIP archive created successfully: ${outputZip}\n`);
+
+    // Load the ZIP to get entry details
+    await zip.loadZipFile(outputZip);
+    const entries = zip.getDirectory();
+
+    // Display summary of compressed files
+    console.log('Compression Summary:');
+    console.log('─'.repeat(80));
+    console.log(
+      padRight('Filename', 30) +
+      padLeft('Original', 10) +
+      padLeft('Compressed', 12) +
+      padLeft('Ratio', 10) +
+      '   ' +
+      padRight('Method', 10)
+    );
+    console.log('─'.repeat(80));
+
+    let totalOriginal = 0;
+    let totalCompressed = 0;
+
+    entries.forEach((entry) => {
+      const filename = entry.filename || '(unnamed)';
+      const original = entry.uncompressedSize || 0;
+      const compressed = entry.compressedSize || 0;
+      const ratio = original > 0 ? ((1 - compressed / original) * 100).toFixed(1) : '0.0';
+      const method = entry.cmpMethodToString();
+
+      totalOriginal += original;
+      totalCompressed += compressed;
+
+      console.log(
+        padRight(filename.length > 28 ? filename.substring(0, 25) + '...' : filename, 30) +
+        padLeft(formatBytes(original), 10) +
+        padLeft(formatBytes(compressed), 12) +
+        padLeft(ratio + '%', 10) +
+        '   ' +
+        padRight(method, 10)
+      );
+    });
+
+    console.log('─'.repeat(80));
+    const totalRatio = totalOriginal > 0 ? ((1 - totalCompressed / totalOriginal) * 100).toFixed(1) : '0.0';
+    console.log(
+      padRight('Total', 30) +
+      padLeft(formatBytes(totalOriginal), 10) +
+      padLeft(formatBytes(totalCompressed), 12) +
+      padLeft(totalRatio + '%', 10) +
+      '   ' +
+      padRight('', 10)
+    );
+    console.log('─'.repeat(80));
+
+    // Verify the ZIP was created
+    if (fs.existsSync(outputZip)) {
+      const zipStats = fs.statSync(outputZip);
+      console.log(`\nArchive file size: ${formatBytes(zipStats.size)}`);
+    }
+
+    console.log('\n💡 Tip: You can also use addFileToZip() for more control:');
+    console.log('   const zip = new ZipkitNode();');
+    console.log('   await zip.addFileToZip("file.txt", "file.txt", options);');
+    console.log('   // ... add more files ...');
+    console.log('   // Then manually write ZIP structure');
+
+  } catch (error) {
+    console.error('❌ Error creating ZIP archive:');
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+// Run the example
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+

package/examples/extract-zip.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+
+/**
+ * Extract ZIP Example
+ * 
+ * Demonstrates extracting files from a ZIP archive using ZipkitNode.
+ * This is a minimal example showing the basic extraction API.
+ */
+
+import ZipkitNode from '../src/node';
+import { crc32 } from '../src/core/encryption/ZipCrypto';
+import * as fs from 'fs';
+import * as path from 'path';
+
+async function main() {
+  console.log('Extracting ZIP archive example...\n');
+
+  // Example: Use the ZIP file created by create-zip.ts
+  // You can also specify your own ZIP file path here
+  const archivePath = path.join(__dirname, 'output', 'example.zip');
+  const destination = path.join(__dirname, 'extracted');
+
+  // Check if ZIP file exists
+  if (!fs.existsSync(archivePath)) {
+    console.error(`❌ ZIP file not found: ${archivePath}`);
+    console.error('💡 Tip: Run create-zip.ts first to create a test ZIP file,');
+    console.error('   or modify archivePath to point to your own ZIP file.');
+    process.exit(1);
+  }
+
+  console.log(`Archive: ${archivePath}`);
+  console.log(`Destination: ${destination}\n`);
+
+  // Create ZipkitNode instance
+  const zip = new ZipkitNode();
+
+  try {
+    // Method 1: Simple API - extract entire ZIP to directory
+    // This is the easiest way to extract a ZIP file
+    console.log('Loading ZIP file...');
+    await zip.loadZipFile(archivePath);
+
+    // Get directory listing to show what will be extracted
+    const entries = zip.getDirectory();
+    console.log(`Found ${entries.length} file(s) in archive:\n`);
+    
+    entries.forEach((entry, index) => {
+      const size = entry.uncompressedSize || 0;
+      const compressed = entry.compressedSize || 0;
+      const method = entry.cmpMethodToString();
+      console.log(`  ${index + 1}. ${entry.filename}`);
+      console.log(`     Size: ${size} bytes (compressed: ${compressed} bytes, ${method})`);
+    });
+    console.log();
+
+    // Extract all files to destination directory
+    console.log('Extracting files...');
+    const result = await zip.extractZipFile(archivePath, destination, {
+      overwrite: true,        // Overwrite existing files
+      preserveTimestamps: true, // Preserve file timestamps
+      skipHashCheck: false    // Verify file integrity (CRC/SHA checks)
+    });
+
+    console.log(`✅ Extraction completed successfully!`);
+    console.log(`   Files extracted: ${result.filesExtracted}`);
+    console.log(`   Total bytes: ${result.bytesExtracted}`);
+
+    // Verify CRC-32 for each extracted file
+    console.log('\nCRC-32 Verification:');
+    const extractedFiles = getAllFiles(destination);
+    let allCrcMatch = true;
+    
+    // Create a map of filename to entry for quick lookup
+    const entryMap = new Map<string, typeof entries[0]>();
+    entries.forEach(entry => {
+      const filename = path.basename(entry.filename);
+      entryMap.set(filename, entry);
+    });
+    
+    extractedFiles.forEach(file => {
+      const relativePath = path.relative(destination, file);
+      const filename = path.basename(file);
+      const stats = fs.statSync(file);
+      const entry = entryMap.get(filename);
+      
+      if (entry) {
+        const storedCrc = entry.crc || 0;
+        const storedCrcHex = `0x${storedCrc.toString(16).padStart(8, '0').toUpperCase()}`;
+        
+        // Calculate CRC-32 of extracted file
+        const fileData = fs.readFileSync(file);
+        const calculatedCrc = crc32(fileData);
+        const calculatedCrcHex = `0x${calculatedCrc.toString(16).padStart(8, '0').toUpperCase()}`;
+        
+        // Compare CRC-32 values
+        const crcMatch = storedCrc === calculatedCrc;
+        const status = crcMatch ? '✓' : '✗';
+        const statusText = crcMatch ? 'PASS' : 'FAILED';
+        
+        if (!crcMatch) {
+          allCrcMatch = false;
+        }
+        
+        console.log(`  ${filename}:`);
+        console.log(`    Stored CRC-32:   ${storedCrcHex}`);
+        console.log(`    Calculated CRC-32: ${calculatedCrcHex}`);
+        console.log(`    Status: ${status} ${statusText}`);
+      } else {
+        console.log(`  ${filename}: Entry not found in ZIP`);
+      }
+    });
+    
+    if (allCrcMatch) {
+      console.log('\n✅ All CRC-32 checks passed!');
+    } else {
+      console.log('\n❌ Some CRC-32 checks failed!');
+    }
+
+    console.log('\n💡 Tip: You can also extract individual entries:');
+    console.log('   await zip.loadZipFile("archive.zip");');
+    console.log('   const entries = zip.getDirectory();');
+    console.log('   await zip.extractToFile(entries[0], "output.txt");');
+
+  } catch (error) {
+    console.error('❌ Error extracting ZIP archive:');
+    console.error(error instanceof Error ? error.message : String(error));
+    if (error instanceof Error && error.stack) {
+      console.error('\nStack trace:');
+      console.error(error.stack);
+    }
+    process.exit(1);
+  }
+}
+
+/**
+ * Helper function to recursively get all files in a directory
+ */
+function getAllFiles(dirPath: string, arrayOfFiles: string[] = []): string[] {
+  const files = fs.readdirSync(dirPath);
+
+  files.forEach((file) => {
+    const filePath = path.join(dirPath, file);
+    if (fs.statSync(filePath).isDirectory()) {
+      arrayOfFiles = getAllFiles(filePath, arrayOfFiles);
+    } else {
+      arrayOfFiles.push(filePath);
+    }
+  });
+
+  return arrayOfFiles;
+}
+
+// Run the example
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+