Add end-to-end encrypted file uploads to your CLI tool: a hands-on walkthrough

footprint drops by 96% compared to in-memory RSA chunking.

• The 4.8% overhead consists of the encrypted symmetric key (~64 bytes for X25519), IV/nonce (12 bytes), and GCM authentication tag (16 bytes) per chunk, plus container metadata.
• Streaming architecture prevents event loop starvation, keeping CLI interactive during uploads.

Core Solution

The production-ready pattern uses Hybrid Authenticated Encryption:

1. Generate an ephemeral AES-256-GCM key per file
2. Encrypt the file stream in chunks
3. Encrypt the AES key with the recipient's X25519 public key
4. Package encrypted data + encrypted key + metadata into a structured upload payload

1. Key Generation & Management

const crypto = require('crypto');

function generateKeyPair() {
  return crypto.generateKeyPairSync('x25519', {
    publicKeyEncoding: { type: 'spki', format: 'pem' },
    privateKeyEncoding: { type: 'pkcs8', format: 'pem' }
  });
}

// Export recipient public key for CLI distribution
function exportPublicKey(publicKey) {
  return publicKey.export({ type: 'spki', format: 'pem' });
}

2. Hybrid Encryption Engine (Streaming)

const fs = require('fs');
const crypto = require('crypto');
const { pipeline } = require('stream/promises');

async function encryptFileForUpload(inputPath, recipientPublicKeyPem, outputPath) {
  const aesKey = crypto.randomBytes(32);
  const iv = crypto.randomBytes(12); // 96-bit nonce for GCM
  
  const cipher = crypto.createCipheriv('aes-256-gcm', aesKey, iv);
  
  // Encrypt AES key with recipient's public key
  const encryptedAesKey = crypto.publicEncrypt(
    { key: recipientPublicKeyPem, padding: crypto.constants.RSA_PKCS1_OAEP_PADDING },
    aesKey
  );

  const writeStream = fs.createWriteStream(outputPath);
  
  // Write header: [4 bytes: encrypted key length][encrypted key][12 bytes: IV]
  const header = Buffer.concat([
    Buffer.alloc(4), // placeholder for key length
    encryptedAesKey,
    iv
  ]);
  header.writeUInt32BE(encryptedAesKey.length, 0);
  writeStream.write(header);

  // Stream file through cipher
  await pipeline(
    fs.createReadStream(inputPath),
    cipher,
    writeStream
  );

  // Append GCM auth tag
  writeStream.write(cipher.getAuthTag());
  writeStream.end();

  return {
    encryptedKey: encryptedAesKey.toString('base64'),
    iv: iv.toString('hex'),
    fileSize: fs.statSync(outputPath).size
  };
}

3. CLI Integration Wrapper

const { Command } = require('commander');
const program = new Command();

program
  .command('upload-report')
  .argument('<file>', 'Path to report file')
  .option('--recipient <key>', 'Recipient public key PEM or path')
  .action(async (file, opts) => {
    const pubKey = opts.recipient.endsWith('.pem') 
      ? fs.readFileSync(opts.recipient, 'utf8') 
      : opts.recipient;
      
    const output = `${file}.enc`;
    console.log(`🔐 Encrypting ${file}...`);
    
    const result = await encryptFileForUpload(file, pubKey, output);
    console.log(`✅ Upload ready: ${output} (${result.fileSize} bytes)`);
    console.log(`📤 Upload payload: ${JSON.stringify(result)}`);
  });

program.parse();

Architecture Decisions:

• X25519 for key exchange: Faster, smaller keys, and resistant to implementation pitfalls compared to RSA. Falls back to RSA-OAEP if legacy compatibility is required.
• AES-256-GCM: Provides both confidentiality and integrity. Authenticated encryption prevents padding oracle and tampering attacks.
• Stream-based pipeline: Leverages Node.js backpressure to maintain constant memory usage regardless of file size.
• Container format: Prepends encrypted key + IV, appends auth tag. Enables stateless decryption without external metadata files.

Pitfall Guide

1. Reusing IV/Nonce with AES-GCM: GCM security collapses if the same nonce is used twice with the same key. Always generate a fresh 12-byte nonce per encryption operation.
2. Blocking the Event Loop with Sync Crypto: crypto.publicEncryptSync() or crypto.createCipheriv() in tight loops freezes CLI responsiveness. Use async stream pipelines or worker_threads for heavy key operations.
3. Ignoring GCM Authentication Tags: Decrypting without verifying authTag allows attackers to modify ciphertext undetected. Always call decipher.setAuthTag() before finalizing decryption.
4. Hardcoding or Committing Private Keys: Storing .pem files in version control or environment variables exposed to logs creates irreversible compromise. Use OS keyrings, dotenv with .gitignore, or hardware security modules (HSMs).
5. In-Memory Buffering for Large Files: fs.readFileSync() or Buffer.concat() on multi-gigabyte reports triggers V8 heap limits. Always use fs.createReadStream() with backpressure-aware pipelines.
6. Weak Padding Schemes: Using RSA_PKCS1_PADDING instead of RSA_PKCS1_OAEP_PADDING enables Bleichenbacher attacks. OAEP provides provable security against chosen-ciphertext attacks.
7. Missing File Integrity Verification: Assuming the upload succeeded without verifying checksums or auth tags leads to corrupted report processing. Implement post-upload validation (e.g., SHA-256 of plaintext hash encrypted alongside the file).

Deliverables

• 📘 Hybrid E2EE Architecture Blueprint: System diagram detailing key lifecycle, stream flow, container format specification, and threat model mapping (STRIDE analysis for CLI upload pipelines).
• ✅ Pre-Deployment Security Checklist: 14-point verification matrix covering key rotation policies, nonce uniqueness guarantees, auth tag validation, dependency auditing (npm audit + Snyk), and CI/CD secret scanning integration.
• ⚙️ Configuration Templates:
  • .env.example with secure variable naming conventions
  • crypto.config.json schema for algorithm selection, chunk sizes, and fallback strategies
  • Dockerfile.security hardening guidelines for CLI containerization (non-root user, read-only filesystem, dropped capabilities)