envx-crypto-tool

ENVX - Secure Environment File Encryption

A secure, password-based encryption tool for .env files that preserves comments and formatting while providing military-grade AES-256-CBC encryption.

Features

• 🔒 AES-256-CBC Encryption - Military-grade encryption with random IVs
• 🔑 Password-based Security - Uses scrypt key derivation (OWASP recommended)
• 📝 Comment Preservation - Keeps all your documentation and formatting intact
• 🛡️ Password Verification - Instant feedback for incorrect passwords
• 🔄 In-Place Operations - Encrypts/decrypts files directly (no copies)
• 📚 Drop-in dotenv Replacement - Compatible with existing dotenv workflows
• 🎯 Smart Detection - Automatically handles encrypted and plain files
• 💻 Cross-Platform - Works on Windows, macOS, and Linux

Quick Start

1. Install ENVX

# Install via npm
npm install envx-crypto-tool

# Or download directly
curl -o envx-crypto-tool.js https://raw.githubusercontent.com/cwdx/envx-crypto-tool/main/envx-crypto-tool.js

2. Basic Usage

# If installed via npm
npx envx encrypt mypassword .env
npx envx decrypt mypassword .env

# If using direct download
node envx-crypto-tool.js encrypt mypassword .env
node envx-crypto-tool.js decrypt mypassword .env

# Your app loads encrypted vars automatically
ENVX_PASSWORD=mypassword node app.js

3. NPM Scripts (Recommended)

Add to your package.json:

{
  "scripts": {
    "start": "sh -c 'ENVX_PASSWORD=\"$0\" node src/index.js'",
    "encrypt": "sh -c 'node envx-crypto-tool.js encrypt \"$0\" .env'",
    "decrypt": "sh -c 'node envx-crypto-tool.js decrypt \"$0\" .env'"
  }
}

Then use:

yarn encrypt mypassword    # Encrypt .env
yarn start mypassword      # Run app with encrypted .env  
yarn decrypt mypassword    # Decrypt .env

Command Line Usage

Encryption & Decryption

# Encrypt file (overwrites original)
envx-crypto-tool encrypt <password> [file]

# Decrypt file (overwrites original) 
envx-crypto-tool decrypt <password> [file]

# Examples
envx-crypto-tool encrypt secret123 .env
envx-crypto-tool decrypt secret123 .env.production

Help & Version

# Show help
envx-crypto-tool --help

# Show version
envx-crypto-tool --version

File Format

Input (.env)

FOO=BAR
API_KEY=secret123
DATABASE_URL=postgres://localhost/mydb

Encrypted Output

#/---------------------------- **[ENVX]** ----------------------------/
#/               password-key encryption for .env files               /
#/                     [how it works](./README.md)                     /
#/--------------------------------------------------------------------/

ENVX_PUBLIC_KEY="baa5a0964d3320fbc0c6a922140453c8"
ENVX_SALT="a1b2c3d4e5f6789012345678901234567890123456789012345678901234"

FOO=aes-256-cbc:c792dd7d7e429420ea1b27ef45491d9a:368a45707d4307d6f62e887cf8845a30
API_KEY=aes-256-cbc:f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6:9z8y7x6w5v4u3t2s1r0q9p8o7n6m5l4k
DATABASE_URL=aes-256-cbc:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6:q1w2e3r4t5y6u7i8o9p0a1s2d3f4g5h6

Format Breakdown

• Header: Comments with tool info and metadata for verification
• Public Key: SHA256 hash of password (first 32 chars) for password verification
• Salt: Random 32-byte salt (64-character hex string) used for key derivation
• Encrypted Values: KEY=aes-256-cbc:IV:ENCRYPTED_DATA
  • IV: 32-character hex string (16 bytes)
  • ENCRYPTED_DATA: Hex-encoded encrypted value

How It Works

Encryption Process

• Salt Generation: Random 32-byte salt generated per file
• Key Derivation: Password → scrypt(password, salt, 32)
• IV Generation: Random 16 bytes per value
• Encryption: AES-256-CBC(value, key, iv)
• Public Key: SHA256(password).substring(0, 32) for verification
• Storage: KEY=aes-256-cbc:IV:ENCRYPTED

Decryption Process

• File Validation: Check for ENVX_PUBLIC_KEY and ENVX_SALT headers
• Salt Extraction: Parse salt from file header
• Password Verification: Compare public keys
• Key Derivation: scrypt(password, salt, 32) using extracted salt
• IV Extraction: Parse IV from each encrypted line
• Decryption: AES-256-CBC-DECRYPT(encrypted, key, iv)
• Output: Clean .env format

Security Features

Password Protection

• scrypt Key Derivation: Slow, memory-hard function prevents brute force
• Public Key Verification: Immediate feedback for wrong passwords
• No Password Storage: Password never stored, only derived keys

Cryptographic Security

• AES-256-CBC: Industry standard encryption algorithm
• Random IVs: Each value gets unique initialization vector
• Random Salt: 32-byte random salt per file prevents rainbow table attacks
• Scrypt Key Derivation: Memory-hard function with unique salt per file

File Integrity

• Header Validation: Ensures file was encrypted by envx
• Format Validation: Strict parsing prevents malformed input
• Error Handling: Graceful failure with helpful messages

Error Handling

The tool provides clear error messages for common issues:

# Missing password
❌ Missing password
Usage: envx-crypto-tool <command> <password> [file]

# File already encrypted
❌ File already encrypted  
Usage: envx-crypto-tool decrypt <password> .env

# Wrong password
❌ Invalid password
Usage: envx-crypto-tool decrypt <correct-password> .env.encrypted

# File not found
❌ File not found: missing.env

API Usage

import { encrypt, decrypt } from './envx-crypto-tool.js';
import crypto from 'crypto';

// Generate salt for encryption
const salt = crypto.randomBytes(32);

// Encrypt text
const result = encrypt("secret-value", "mypassword", salt);
console.log(result); // { iv: "a1b2c3...", encrypted: "9z8y7x..." }

// Decrypt text  
const decrypted = decrypt("9z8y7x...", "a1b2c3...", "mypassword", salt);
console.log(decrypted); // "secret-value"

Use Cases

• Development: Encrypt .env files before committing to git
• Production: Secure environment variable storage
• CI/CD: Decrypt environment files in build pipelines
• Backup: Encrypted storage of sensitive configuration
• Sharing: Secure sharing of environment configurations

Workflow Examples

Git Workflow

# Before committing sensitive .env
cp .env .env.backup                         # Backup original
envx-crypto-tool encrypt mypass123 .env    # Encrypt in place
git add .env                           # Commit encrypted version
git commit -m "Add encrypted env"

# After pulling encrypted .env
envx-crypto-tool decrypt mypass123 .env    # Decrypt in place
# Now .env contains plaintext for development

CI/CD Pipeline

# In your deployment script
envx-crypto-tool decrypt $ENV_PASSWORD .env.production
# App can now read decrypted environment variables

License

Proprietary - All rights reserved

Contributing

Issues and pull requests welcome!