stegdoc 4.0.0 → 5.0.0

package/src/commands/decode.js

@@ -1,343 +1,485 @@
-const path = require('path');
-const fs = require('fs');
-const { finished } = require('stream/promises');
-const chalk = require('chalk');
-const ora = require('ora');
-const { readDocxBase64, } = require('../lib/docx-handler');
-const { readXlsxBase64 } = require('../lib/xlsx-handler');
-const { validateMetadata, isMultiPart, isStreamingFormat } = require('../lib/metadata');
-const { detectFormat, formatBytes, generateContentHash } = require('../lib/utils');
-const { decrypt, unpackEncryptionMeta, createDecryptStream } = require('../lib/crypto');
-const { decompress, createDecompressStream } = require('../lib/compression');
-const { promptPassword, promptOverwrite } = require('../lib/interactive');
-const { extractContent, findMultiPartFiles, mergeBase64Chunks } = require('../lib/file-utils');
-const { HashPassthrough } = require('../lib/streams');
-
-/**
- * Read file based on format
- * @param {string} filePath - Path to file
- * @param {string} format - File format
- * @returns {Promise<object>} Read result
- */
-async function readFile(filePath, format) {
-  if (format === 'xlsx') {
-    return await readXlsxBase64(filePath);
-  } else {
-    return await readDocxBase64(filePath);
-  }
-}
-
-/**
- * Decode a DOCX/XLSX file back to original format
- * @param {string} inputFile - Path to input file
- * @param {object} options - Command options
- */
-async function decodeCommand(inputFile, options) {
-  const quiet = options.quiet || false;
-  const spinner = quiet ? { start: () => {}, succeed: () => {}, fail: () => {}, info: () => {}, warn: () => {}, text: '' } : ora('Starting decoding process...').start();
-
-  try {
-    // Detect format from extension
-    const format = detectFormat(inputFile);
-    if (!format) {
-      throw new Error('Unknown file format. Supported formats: .xlsx, .docx');
-    }
-
-    spinner.text = `Reading ${format.toUpperCase()} file...`;
-
-    // Read the first file
-    const readResult = await readFile(inputFile, format);
-    const { encryptedContent, encryptionMeta, metadata } = extractContent(readResult, format);
-
-    // Validate metadata
-    validateMetadata(metadata);
-
-    const isEncrypted = metadata.encrypted || (encryptionMeta && encryptionMeta.length > 0);
-    const isCompressed = metadata.compressed || false;
-
-    spinner.succeed && spinner.succeed(`${format.toUpperCase()} file read successfully`);
-
-    if (!quiet) {
-      console.log(chalk.cyan(`  Original file: ${metadata.originalFilename}`));
-      console.log(chalk.cyan(`  Original size: ${formatBytes(metadata.originalSize)}`));
-      console.log(chalk.cyan(`  Encrypted: ${isEncrypted ? 'Yes' : 'No'}`));
-      console.log(chalk.cyan(`  Compressed: ${isCompressed ? 'Yes' : 'No'}`));
-    }
-
-    // Check password for encrypted files - prompt if not provided and not in quiet mode
-    if (isEncrypted && !options.password) {
-      if (quiet || options.yes) {
-        throw new Error('Password is required for encrypted files. Use -p or --password to specify.');
-      }
-      options.password = await promptPassword();
-    }
-
-    // Determine output path and check overwrite
-    let outputPath;
-    if (options.output) {
-      if (fs.existsSync(options.output) && fs.statSync(options.output).isDirectory()) {
-        outputPath = path.join(options.output, metadata.originalFilename);
-      } else if (!path.extname(options.output) && !fs.existsSync(options.output)) {
-        fs.mkdirSync(options.output, { recursive: true });
-        outputPath = path.join(options.output, metadata.originalFilename);
-      } else {
-        outputPath = options.output;
-      }
-    } else {
-      outputPath = path.join(process.cwd(), metadata.originalFilename);
-    }
-
-    if (fs.existsSync(outputPath) && !options.force) {
-      if (quiet || options.yes) {
-        throw new Error(`File already exists: ${outputPath}. Use --force to overwrite.`);
-      }
-      const shouldOverwrite = await promptOverwrite(outputPath);
-      if (!shouldOverwrite) {
-        console.log(chalk.yellow('Operation cancelled.'));
-        process.exit(0);
-      }
-    }
-
-    // Route to v4 streaming decode or legacy decode
-    if (isStreamingFormat(metadata)) {
-      await decodeStreaming(inputFile, format, metadata, encryptedContent, encryptionMeta, isEncrypted, isCompressed, options, outputPath, spinner, quiet);
-    } else {
-      await decodeLegacy(inputFile, format, metadata, encryptedContent, encryptionMeta, isEncrypted, isCompressed, options, outputPath, spinner, quiet);
-    }
-  } catch (error) {
-    spinner.fail && spinner.fail('Decoding failed');
-    console.error(chalk.red(`Error: ${error.message}`));
-    process.exit(1);
-  }
-}
-
-/**
- * v4 streaming decode — per-part decryption, streaming decompress and write
- */
-async function decodeStreaming(inputFile, format, metadata, encryptedContent, encryptionMeta, isEncrypted, isCompressed, options, outputPath, spinner, quiet) {
-  // Ensure output directory exists
-  const outputDir = path.dirname(outputPath);
-  if (!fs.existsSync(outputDir)) {
-    fs.mkdirSync(outputDir, { recursive: true });
-  }
-
-  // Set up output pipeline: [decompress] → hash → file
-  const hashStream = new HashPassthrough();
-  const outputStream = fs.createWriteStream(outputPath);
-
-  let decompressStream = null;
-  if (isCompressed) {
-    decompressStream = createDecompressStream();
-    decompressStream.pipe(hashStream).pipe(outputStream);
-  } else {
-    hashStream.pipe(outputStream);
-  }
-
-  const writeTarget = isCompressed ? decompressStream : hashStream;
-
-  // v4 files may have partNumber set but totalParts null (unknown at encode time).
-  // Detect multi-part by checking partNumber OR totalParts.
-  const hasMultipleParts = isMultiPart(metadata) || metadata.partNumber !== null;
-  let totalPartsFound = 1;
-
-  if (hasMultipleParts) {
-    // Find all parts by filename matching
-    const inputDir = path.dirname(inputFile);
-    const allParts = findMultiPartFiles(inputDir, metadata.hash, format);
-    totalPartsFound = allParts.length;
-
-    // Validate against totalParts if available
-    if (metadata.totalParts !== null && totalPartsFound !== metadata.totalParts) {
-      throw new Error(
-        `Missing parts! Found ${totalPartsFound} of ${metadata.totalParts} parts. ` +
-        `Make sure all parts are in the same directory.`
-      );
-    }
-
-    spinner.text = `Multi-part file detected (${totalPartsFound} parts)`;
-    spinner.succeed && spinner.succeed(`Found all ${totalPartsFound} parts`);
-
-    // Process each part
-    for (let i = 0; i < allParts.length; i++) {
-      const partSpinner = quiet ? spinner : ora(`Decoding part ${i + 1} of ${totalPartsFound}...`).start();
-
-      const partResult = await readFile(allParts[i].path, format);
-      const { encryptedContent: partContent, encryptionMeta: partEncMeta } = extractContent(partResult, format);
-
-      // Decode base64 to binary
-      const binaryData = Buffer.from(partContent, 'base64');
-
-      if (isEncrypted) {
-        // Each part has its own encryption metadata (per-part encryption)
-        const { iv, salt, authTag } = unpackEncryptionMeta(partEncMeta);
-        const decipher = createDecryptStream(options.password, iv, salt, authTag);
-        try {
-          const decrypted = Buffer.concat([decipher.update(binaryData), decipher.final()]);
-          writeTarget.write(decrypted);
-        } catch (error) {
-          throw new Error('Decryption failed: Invalid password or corrupted data');
-        }
-      } else {
-        writeTarget.write(binaryData);
-      }
-
-      partSpinner.succeed && partSpinner.succeed(`Part ${i + 1} decoded`);
-    }
-  } else {
-    // Single file
-    spinner.text = 'Decoding...';
-
-    const binaryData = Buffer.from(encryptedContent, 'base64');
-
-    if (isEncrypted) {
-      const { iv, salt, authTag } = unpackEncryptionMeta(encryptionMeta);
-      const decipher = createDecryptStream(options.password, iv, salt, authTag);
-      try {
-        const decrypted = Buffer.concat([decipher.update(binaryData), decipher.final()]);
-        writeTarget.write(decrypted);
-      } catch (error) {
-        throw new Error('Decryption failed: Invalid password or corrupted data');
-      }
-    } else {
-      writeTarget.write(binaryData);
-    }
-  }
-
-  // End the pipeline and wait for it to finish
-  writeTarget.end();
-  await finished(outputStream);
-
-  // Verify integrity
-  if (metadata.contentHash) {
-    spinner.text = 'Verifying integrity...';
-    const actualHash = hashStream.digest;
-
-    if (actualHash !== metadata.contentHash) {
-      // Clean up the output file on integrity failure
-      try { fs.unlinkSync(outputPath); } catch { /* ignore */ }
-      throw new Error('Integrity check failed! The file may be corrupted or tampered with.');
-    }
-    spinner.succeed && spinner.succeed('Integrity verified (SHA-256 match)');
-  }
-
-  spinner.succeed && spinner.succeed('Decoding complete!');
-
-  if (!quiet) {
-    const outputSize = fs.statSync(outputPath).size;
-    console.log();
-    console.log(chalk.green.bold('✓ File decoded successfully!'));
-    console.log(chalk.cyan(`  Original: ${metadata.originalFilename}`));
-    console.log(chalk.cyan(`  Output: ${outputPath}`));
-    console.log(chalk.cyan(`  Size: ${formatBytes(outputSize)}`));
-    if (hasMultipleParts) {
-      console.log(chalk.cyan(`  Parts merged: ${totalPartsFound}`));
-    }
-  }
-}
-
-/**
- * Legacy v3 in-memory decode — shared encryption across all parts
- */
-async function decodeLegacy(inputFile, format, metadata, encryptedContent, encryptionMeta, isEncrypted, isCompressed, options, outputPath, spinner, quiet) {
-  let finalBase64;
-
-  if (isMultiPart(metadata)) {
-    spinner.start && (spinner.text = `Multi-part file detected (${metadata.totalParts} parts)`);
-
-    // Find all parts
-    const inputDir = path.dirname(inputFile);
-    const allParts = findMultiPartFiles(inputDir, metadata.hash, format, metadata.totalParts);
-
-    if (allParts.length !== metadata.totalParts) {
-      throw new Error(
-        `Missing parts! Found ${allParts.length} of ${metadata.totalParts} parts. ` +
-        `Make sure all parts are in the same directory.`
-      );
-    }
-
-    spinner.succeed && spinner.succeed(`Found all ${metadata.totalParts} parts`);
-
-    // Read all parts
-    const chunks = [];
-
-    for (let i = 0; i < allParts.length; i++) {
-      const partSpinner = quiet ? spinner : ora(`Reading part ${i + 1} of ${metadata.totalParts}...`).start();
-      const partResult = await readFile(allParts[i].path, format);
-      const { encryptedContent: partContent } = extractContent(partResult, format);
-      chunks.push(partContent);
-      partSpinner.succeed && partSpinner.succeed(`Part ${i + 1} read`);
-    }
-
-    // Merge chunks
-    spinner.text = 'Merging parts...';
-    const mergedContent = mergeBase64Chunks(chunks);
-    spinner.succeed && spinner.succeed('Parts merged successfully');
-
-    // Decrypt if needed
-    if (isEncrypted) {
-      spinner.text = 'Decrypting content...';
-      const { iv, salt, authTag } = unpackEncryptionMeta(encryptionMeta);
-      finalBase64 = decrypt(mergedContent, options.password, iv, salt, authTag);
-      spinner.succeed && spinner.succeed('Content decrypted');
-    } else {
-      finalBase64 = mergedContent;
-    }
-  } else {
-    // Single file - Decrypt if needed
-    if (isEncrypted) {
-      spinner.text = 'Decrypting content...';
-      const { iv, salt, authTag } = unpackEncryptionMeta(encryptionMeta);
-      finalBase64 = decrypt(encryptedContent, options.password, iv, salt, authTag);
-      spinner.succeed && spinner.succeed('Content decrypted');
-    } else {
-      finalBase64 = encryptedContent;
-    }
-  }
-
-  // Decompress if needed
-  let fileBuffer;
-  if (isCompressed) {
-    spinner.text = 'Decompressing...';
-    const compressedBuffer = Buffer.from(finalBase64, 'base64');
-    fileBuffer = await decompress(compressedBuffer);
-    spinner.succeed && spinner.succeed(`Decompressed: ${formatBytes(compressedBuffer.length)} → ${formatBytes(fileBuffer.length)}`);
-  } else {
-    fileBuffer = Buffer.from(finalBase64, 'base64');
-  }
-
-  // Verify integrity if content hash is available
-  if (metadata.contentHash) {
-    spinner.text = 'Verifying integrity...';
-    const actualHash = generateContentHash(fileBuffer);
-
-    if (actualHash !== metadata.contentHash) {
-      throw new Error('Integrity check failed! The file may be corrupted or tampered with.');
-    }
-    spinner.succeed && spinner.succeed('Integrity verified (SHA-256 match)');
-  }
-
-  // Write to file
-  spinner.text = 'Writing output file...';
-
-  const outputDir = path.dirname(outputPath);
-  if (!fs.existsSync(outputDir)) {
-    fs.mkdirSync(outputDir, { recursive: true });
-  }
-
-  fs.writeFileSync(outputPath, fileBuffer);
-
-  spinner.succeed && spinner.succeed('Decoding complete!');
-
-  if (!quiet) {
-    console.log();
-    console.log(chalk.green.bold('✓ File decoded successfully!'));
-    console.log(chalk.cyan(`  Original: ${metadata.originalFilename}`));
-    console.log(chalk.cyan(`  Output: ${outputPath}`));
-    console.log(chalk.cyan(`  Size: ${formatBytes(fileBuffer.length)}`));
-    if (isMultiPart(metadata)) {
-      console.log(chalk.cyan(`  Parts merged: ${metadata.totalParts}`));
-    }
-  }
-}
-
-module.exports = decodeCommand;
+const path = require('path');
+const fs = require('fs');
+const { finished } = require('stream/promises');
+const chalk = require('chalk');
+const ora = require('ora');
+const { readDocxBase64, } = require('../lib/docx-handler');
+const { readXlsxBase64, readXlsxV5 } = require('../lib/xlsx-handler');
+const { validateMetadata, isMultiPart, isStreamingFormat, isLogEmbedFormat, parseMetadata } = require('../lib/metadata');
+const { detectFormat, formatBytes, generateContentHash } = require('../lib/utils');
+const { decrypt, unpackEncryptionMeta, createDecryptStream } = require('../lib/crypto');
+const { decompress, createDecompressStream, decompressBrotli, createBrotliDecompressStream } = require('../lib/compression');
+const { promptPassword, promptOverwrite } = require('../lib/interactive');
+const { extractContent, findMultiPartFiles, mergeBase64Chunks } = require('../lib/file-utils');
+const { HashPassthrough } = require('../lib/streams');
+
+/**
+ * Read file based on format
+ */
+async function readFile(filePath, format) {
+  if (format === 'xlsx') {
+    return await readXlsxBase64(filePath);
+  } else {
+    return await readDocxBase64(filePath);
+  }
+}
+
+/**
+ * Decode a DOCX/XLSX file back to original format
+ */
+async function decodeCommand(inputFile, options) {
+  const quiet = options.quiet || false;
+  const spinner = quiet ? { start: () => {}, succeed: () => {}, fail: () => {}, info: () => {}, warn: () => {}, text: '' } : ora('Starting decoding process...').start();
+
+  try {
+    const format = detectFormat(inputFile);
+    if (!format) {
+      throw new Error('Unknown file format. Supported formats: .xlsx, .docx');
+    }
+
+    spinner.text = `Reading ${format.toUpperCase()} file...`;
+
+    // Read the first file
+    const readResult = await readFile(inputFile, format);
+
+    // Route based on format version
+    if (readResult.formatVersion === 'v5') {
+      await decodeV5(inputFile, format, readResult, options, spinner, quiet);
+    } else {
+      // Legacy v3/v4 path
+      const { encryptedContent, encryptionMeta, metadata } = extractContent(readResult, format);
+      validateMetadata(metadata);
+
+      const isEncrypted = metadata.encrypted || (encryptionMeta && encryptionMeta.length > 0);
+      const isCompressed = metadata.compressed || false;
+
+      spinner.succeed && spinner.succeed(`${format.toUpperCase()} file read successfully`);
+
+      if (!quiet) {
+        console.log(chalk.cyan(`  Original file: ${metadata.originalFilename}`));
+        console.log(chalk.cyan(`  Original size: ${formatBytes(metadata.originalSize)}`));
+        console.log(chalk.cyan(`  Encrypted: ${isEncrypted ? 'Yes' : 'No'}`));
+        console.log(chalk.cyan(`  Compressed: ${isCompressed ? 'Yes' : 'No'}`));
+      }
+
+      if (isEncrypted && !options.password) {
+        if (quiet || options.yes) {
+          throw new Error('Password is required for encrypted files. Use -p or --password to specify.');
+        }
+        options.password = await promptPassword();
+      }
+
+      let outputPath = resolveOutputPath(options, metadata);
+
+      if (fs.existsSync(outputPath) && !options.force) {
+        if (quiet || options.yes) {
+          throw new Error(`File already exists: ${outputPath}. Use --force to overwrite.`);
+        }
+        const shouldOverwrite = await promptOverwrite(outputPath);
+        if (!shouldOverwrite) {
+          console.log(chalk.yellow('Operation cancelled.'));
+          process.exit(0);
+        }
+      }
+
+      if (isStreamingFormat(metadata) && format === 'xlsx') {
+        await decodeStreaming(inputFile, format, metadata, encryptedContent, encryptionMeta, isEncrypted, isCompressed, options, outputPath, spinner, quiet);
+      } else {
+        await decodeLegacy(inputFile, format, metadata, encryptedContent, encryptionMeta, isEncrypted, isCompressed, options, outputPath, spinner, quiet);
+      }
+    }
+  } catch (error) {
+    spinner.fail && spinner.fail('Decoding failed');
+    console.error(chalk.red(`Error: ${error.message}`));
+    process.exit(1);
+  }
+}
+
+/**
+ * Resolve output path from options and metadata
+ */
+function resolveOutputPath(options, metadata) {
+  if (options.output) {
+    if (fs.existsSync(options.output) && fs.statSync(options.output).isDirectory()) {
+      return path.join(options.output, metadata.originalFilename);
+    } else if (!path.extname(options.output) && !fs.existsSync(options.output)) {
+      fs.mkdirSync(options.output, { recursive: true });
+      return path.join(options.output, metadata.originalFilename);
+    } else {
+      return options.output;
+    }
+  }
+  return path.join(process.cwd(), metadata.originalFilename);
+}
+
+// ─── v5 Log-Embed Decode ────────────────────────────────────────────────────
+
+/**
+ * Decode a v5 log-embed XLSX file
+ */
+async function decodeV5(inputFile, format, firstReadResult, options, spinner, quiet) {
+  const metadata = firstReadResult.metadata;
+  validateMetadata(metadata);
+
+  const isEncrypted = metadata.encrypted || false;
+  const isCompressed = metadata.compressed || false;
+  const compressionAlgo = metadata.compressionAlgo || 'brotli';
+
+  spinner.succeed && spinner.succeed(`${format.toUpperCase()} file read (v5 log-embed format)`);
+
+  if (!quiet) {
+    console.log(chalk.cyan(`  Original file: ${metadata.originalFilename}`));
+    console.log(chalk.cyan(`  Original size: ${formatBytes(metadata.originalSize)}`));
+    console.log(chalk.cyan(`  Encrypted: ${isEncrypted ? 'Yes' : 'No'}`));
+    console.log(chalk.cyan(`  Compressed: ${isCompressed ? `Yes (${compressionAlgo})` : 'No'}`));
+  }
+
+  if (isEncrypted && !options.password) {
+    if (quiet || options.yes) {
+      throw new Error('Password is required for encrypted files. Use -p or --password to specify.');
+    }
+    options.password = await promptPassword();
+  }
+
+  let outputPath = resolveOutputPath(options, metadata);
+
+  if (fs.existsSync(outputPath) && !options.force) {
+    if (quiet || options.yes) {
+      throw new Error(`File already exists: ${outputPath}. Use --force to overwrite.`);
+    }
+    const shouldOverwrite = await promptOverwrite(outputPath);
+    if (!shouldOverwrite) {
+      console.log(chalk.yellow('Operation cancelled.'));
+      process.exit(0);
+    }
+  }
+
+  // Ensure output directory exists
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Set up output pipeline: [decompress] → hash → file
+  const hashStream = new HashPassthrough();
+  const outputStream = fs.createWriteStream(outputPath);
+
+  let decompressStream = null;
+  if (isCompressed) {
+    if (compressionAlgo === 'brotli') {
+      decompressStream = createBrotliDecompressStream();
+    } else {
+      decompressStream = createDecompressStream();
+    }
+    decompressStream.pipe(hashStream).pipe(outputStream);
+  } else {
+    hashStream.pipe(outputStream);
+  }
+
+  const writeTarget = isCompressed ? decompressStream : hashStream;
+
+  // Check for multi-part
+  const hasMultipleParts = isMultiPart(metadata) || metadata.partNumber !== null;
+  let totalPartsFound = 1;
+
+  if (hasMultipleParts) {
+    const inputDir = path.dirname(inputFile);
+    const allParts = findMultiPartFiles(inputDir, metadata.hash, format);
+    totalPartsFound = allParts.length;
+
+    if (metadata.totalParts !== null && totalPartsFound !== metadata.totalParts) {
+      throw new Error(
+        `Missing parts! Found ${totalPartsFound} of ${metadata.totalParts} parts. ` +
+        `Make sure all parts are in the same directory.`
+      );
+    }
+
+    spinner.text = `Multi-part file detected (${totalPartsFound} parts)`;
+    spinner.succeed && spinner.succeed(`Found all ${totalPartsFound} parts`);
+
+    for (let i = 0; i < allParts.length; i++) {
+      const partSpinner = quiet ? spinner : ora(`Decoding part ${i + 1} of ${totalPartsFound}...`).start();
+
+      const partResult = await readFile(allParts[i].path, format);
+
+      let partPayload;
+      let partEncMeta;
+
+      if (partResult.formatVersion === 'v5') {
+        partPayload = partResult.payloadBuffer;
+        partEncMeta = partResult.encryptionMeta;
+      } else {
+        // Shouldn't happen for v5, but handle gracefully
+        const extracted = extractContent(partResult, format);
+        partPayload = Buffer.from(extracted.encryptedContent, 'base64');
+        partEncMeta = extracted.encryptionMeta;
+      }
+
+      if (isEncrypted) {
+        const { iv, salt, authTag } = unpackEncryptionMeta(partEncMeta);
+        const decipher = createDecryptStream(options.password, iv, salt, authTag);
+        try {
+          const decrypted = Buffer.concat([decipher.update(partPayload), decipher.final()]);
+          writeTarget.write(decrypted);
+        } catch (error) {
+          throw new Error('Decryption failed: Invalid password or corrupted data');
+        }
+      } else {
+        writeTarget.write(partPayload);
+      }
+
+      partSpinner.succeed && partSpinner.succeed(`Part ${i + 1} decoded`);
+    }
+  } else {
+    // Single file
+    spinner.text = 'Decoding...';
+
+    const payloadBuffer = firstReadResult.payloadBuffer;
+    const encryptionMeta = firstReadResult.encryptionMeta;
+
+    if (isEncrypted) {
+      const { iv, salt, authTag } = unpackEncryptionMeta(encryptionMeta);
+      const decipher = createDecryptStream(options.password, iv, salt, authTag);
+      try {
+        const decrypted = Buffer.concat([decipher.update(payloadBuffer), decipher.final()]);
+        writeTarget.write(decrypted);
+      } catch (error) {
+        throw new Error('Decryption failed: Invalid password or corrupted data');
+      }
+    } else {
+      writeTarget.write(payloadBuffer);
+    }
+  }
+
+  // End pipeline and wait
+  writeTarget.end();
+  await finished(outputStream);
+
+  // Verify integrity
+  if (metadata.contentHash) {
+    spinner.text = 'Verifying integrity...';
+    const actualHash = hashStream.digest;
+    if (actualHash !== metadata.contentHash) {
+      try { fs.unlinkSync(outputPath); } catch { /* ignore */ }
+      throw new Error('Integrity check failed! The file may be corrupted or tampered with.');
+    }
+    spinner.succeed && spinner.succeed('Integrity verified (SHA-256 match)');
+  }
+
+  spinner.succeed && spinner.succeed('Decoding complete!');
+
+  if (!quiet) {
+    const outputSize = fs.statSync(outputPath).size;
+    console.log();
+    console.log(chalk.green.bold('✓ File decoded successfully!'));
+    console.log(chalk.cyan(`  Original: ${metadata.originalFilename}`));
+    console.log(chalk.cyan(`  Output: ${outputPath}`));
+    console.log(chalk.cyan(`  Size: ${formatBytes(outputSize)}`));
+    if (hasMultipleParts) {
+      console.log(chalk.cyan(`  Parts merged: ${totalPartsFound}`));
+    }
+  }
+}
+
+// ─── v4 Streaming Decode ────────────────────────────────────────────────────
+
+async function decodeStreaming(inputFile, format, metadata, encryptedContent, encryptionMeta, isEncrypted, isCompressed, options, outputPath, spinner, quiet) {
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  const hashStream = new HashPassthrough();
+  const outputStream = fs.createWriteStream(outputPath);
+
+  let decompressStream = null;
+  if (isCompressed) {
+    decompressStream = createDecompressStream();
+    decompressStream.pipe(hashStream).pipe(outputStream);
+  } else {
+    hashStream.pipe(outputStream);
+  }
+
+  const writeTarget = isCompressed ? decompressStream : hashStream;
+
+  const hasMultipleParts = isMultiPart(metadata) || metadata.partNumber !== null;
+  let totalPartsFound = 1;
+
+  if (hasMultipleParts) {
+    const inputDir = path.dirname(inputFile);
+    const allParts = findMultiPartFiles(inputDir, metadata.hash, format);
+    totalPartsFound = allParts.length;
+
+    if (metadata.totalParts !== null && totalPartsFound !== metadata.totalParts) {
+      throw new Error(
+        `Missing parts! Found ${totalPartsFound} of ${metadata.totalParts} parts. ` +
+        `Make sure all parts are in the same directory.`
+      );
+    }
+
+    spinner.text = `Multi-part file detected (${totalPartsFound} parts)`;
+    spinner.succeed && spinner.succeed(`Found all ${totalPartsFound} parts`);
+
+    for (let i = 0; i < allParts.length; i++) {
+      const partSpinner = quiet ? spinner : ora(`Decoding part ${i + 1} of ${totalPartsFound}...`).start();
+
+      const partResult = await readFile(allParts[i].path, format);
+      const { encryptedContent: partContent, encryptionMeta: partEncMeta } = extractContent(partResult, format);
+
+      const binaryData = Buffer.from(partContent, 'base64');
+
+      if (isEncrypted) {
+        const { iv, salt, authTag } = unpackEncryptionMeta(partEncMeta);
+        const decipher = createDecryptStream(options.password, iv, salt, authTag);
+        try {
+          const decrypted = Buffer.concat([decipher.update(binaryData), decipher.final()]);
+          writeTarget.write(decrypted);
+        } catch (error) {
+          throw new Error('Decryption failed: Invalid password or corrupted data');
+        }
+      } else {
+        writeTarget.write(binaryData);
+      }
+
+      partSpinner.succeed && partSpinner.succeed(`Part ${i + 1} decoded`);
+    }
+  } else {
+    spinner.text = 'Decoding...';
+    const binaryData = Buffer.from(encryptedContent, 'base64');
+
+    if (isEncrypted) {
+      const { iv, salt, authTag } = unpackEncryptionMeta(encryptionMeta);
+      const decipher = createDecryptStream(options.password, iv, salt, authTag);
+      try {
+        const decrypted = Buffer.concat([decipher.update(binaryData), decipher.final()]);
+        writeTarget.write(decrypted);
+      } catch (error) {
+        throw new Error('Decryption failed: Invalid password or corrupted data');
+      }
+    } else {
+      writeTarget.write(binaryData);
+    }
+  }
+
+  writeTarget.end();
+  await finished(outputStream);
+
+  if (metadata.contentHash) {
+    spinner.text = 'Verifying integrity...';
+    const actualHash = hashStream.digest;
+    if (actualHash !== metadata.contentHash) {
+      try { fs.unlinkSync(outputPath); } catch { /* ignore */ }
+      throw new Error('Integrity check failed! The file may be corrupted or tampered with.');
+    }
+    spinner.succeed && spinner.succeed('Integrity verified (SHA-256 match)');
+  }
+
+  spinner.succeed && spinner.succeed('Decoding complete!');
+
+  if (!quiet) {
+    const outputSize = fs.statSync(outputPath).size;
+    console.log();
+    console.log(chalk.green.bold('✓ File decoded successfully!'));
+    console.log(chalk.cyan(`  Original: ${metadata.originalFilename}`));
+    console.log(chalk.cyan(`  Output: ${outputPath}`));
+    console.log(chalk.cyan(`  Size: ${formatBytes(outputSize)}`));
+    if (hasMultipleParts) {
+      console.log(chalk.cyan(`  Parts merged: ${totalPartsFound}`));
+    }
+  }
+}
+
+// ─── v3 Legacy Decode ───────────────────────────────────────────────────────
+
+async function decodeLegacy(inputFile, format, metadata, encryptedContent, encryptionMeta, isEncrypted, isCompressed, options, outputPath, spinner, quiet) {
+  let finalBase64;
+
+  if (isMultiPart(metadata)) {
+    spinner.start && (spinner.text = `Multi-part file detected (${metadata.totalParts} parts)`);
+
+    const inputDir = path.dirname(inputFile);
+    const allParts = findMultiPartFiles(inputDir, metadata.hash, format, metadata.totalParts);
+
+    if (allParts.length !== metadata.totalParts) {
+      throw new Error(
+        `Missing parts! Found ${allParts.length} of ${metadata.totalParts} parts. ` +
+        `Make sure all parts are in the same directory.`
+      );
+    }
+
+    spinner.succeed && spinner.succeed(`Found all ${metadata.totalParts} parts`);
+
+    const chunks = [];
+    for (let i = 0; i < allParts.length; i++) {
+      const partSpinner = quiet ? spinner : ora(`Reading part ${i + 1} of ${metadata.totalParts}...`).start();
+      const partResult = await readFile(allParts[i].path, format);
+      const { encryptedContent: partContent } = extractContent(partResult, format);
+      chunks.push(partContent);
+      partSpinner.succeed && partSpinner.succeed(`Part ${i + 1} read`);
+    }
+
+    spinner.text = 'Merging parts...';
+    const mergedContent = mergeBase64Chunks(chunks);
+    spinner.succeed && spinner.succeed('Parts merged successfully');
+
+    if (isEncrypted) {
+      spinner.text = 'Decrypting content...';
+      const { iv, salt, authTag } = unpackEncryptionMeta(encryptionMeta);
+      finalBase64 = decrypt(mergedContent, options.password, iv, salt, authTag);
+      spinner.succeed && spinner.succeed('Content decrypted');
+    } else {
+      finalBase64 = mergedContent;
+    }
+  } else {
+    if (isEncrypted) {
+      spinner.text = 'Decrypting content...';
+      const { iv, salt, authTag } = unpackEncryptionMeta(encryptionMeta);
+      finalBase64 = decrypt(encryptedContent, options.password, iv, salt, authTag);
+      spinner.succeed && spinner.succeed('Content decrypted');
+    } else {
+      finalBase64 = encryptedContent;
+    }
+  }
+
+  let fileBuffer;
+  if (isCompressed) {
+    spinner.text = 'Decompressing...';
+    const compressedBuffer = Buffer.from(finalBase64, 'base64');
+    fileBuffer = await decompress(compressedBuffer);
+    spinner.succeed && spinner.succeed(`Decompressed: ${formatBytes(compressedBuffer.length)} → ${formatBytes(fileBuffer.length)}`);
+  } else {
+    fileBuffer = Buffer.from(finalBase64, 'base64');
+  }
+
+  if (metadata.contentHash) {
+    spinner.text = 'Verifying integrity...';
+    const actualHash = generateContentHash(fileBuffer);
+    if (actualHash !== metadata.contentHash) {
+      throw new Error('Integrity check failed! The file may be corrupted or tampered with.');
+    }
+    spinner.succeed && spinner.succeed('Integrity verified (SHA-256 match)');
+  }
+
+  spinner.text = 'Writing output file...';
+  const outputDir = path.dirname(outputPath);
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  fs.writeFileSync(outputPath, fileBuffer);
+
+  spinner.succeed && spinner.succeed('Decoding complete!');
+
+  if (!quiet) {
+    console.log();
+    console.log(chalk.green.bold('✓ File decoded successfully!'));
+    console.log(chalk.cyan(`  Original: ${metadata.originalFilename}`));
+    console.log(chalk.cyan(`  Output: ${outputPath}`));
+    console.log(chalk.cyan(`  Size: ${formatBytes(fileBuffer.length)}`));
+    if (isMultiPart(metadata)) {
+      console.log(chalk.cyan(`  Parts merged: ${metadata.totalParts}`));
+    }
+  }
+}
+
+module.exports = decodeCommand;