hidenv/README.md

Beautiful CLI tool to encrypt and decrypt .env files with AES-256-GCM

# 🔐 HidEnv - Secure Environment Tool

A beautiful CLI tool to encrypt and decrypt `.env` files using military-grade AES-256-GCM encryption. Keep your secrets safe! 🛡️

![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)
![Node](https://img.shields.io/badge/node-%3E%3D16-green.svg)
![License](https://img.shields.io/badge/license-MIT-yellow.svg)

## 🚀 Quick Start

```bash
# Install globally
npm install -g hidenv

# Quick test (try it now!)
echo "TEST_VAR=hello_world" > .env
hidenv --e mypassword    # Encrypt
hidenv --d mypassword    # Decrypt
cat .env                 # Verify: should show TEST_VAR=hello_world

# That's it! Your .env is now safely encrypted as .env.enc
```

### ⚡ One-Minute Test

Want to see it in action right now?

```bash
# Create test file
echo "DEMO=this_is_a_test" > .env

# Encrypt it
hidenv --e demo123

# Remove original
rm .env

# Decrypt it back
hidenv --d demo123

# Check it worked
cat .env
# Output: DEMO=this_is_a_test
```

## 🌟 Features

- 🔒 **Military-Grade Encryption**: AES-256-GCM with scrypt key derivation
- 🎨 **Beautiful Interface**: Interactive CLI with colors, spinners, and ASCII art
- ⚡ **Lightning Fast**: Direct encryption/decryption with command arguments
- 🔑 **Secure Input**: Password masking and validation
- 🌍 **Cross-Platform**: Works on Windows, macOS, and Linux
- 📦 **Zero Dependencies**: Only crypto built-ins, no external crypto libraries

## 🚀 Installation

### Global Installation

```bash
npm install -g secure-env-tool
```

### Local Installation

```bash
git clone <repository-url>
cd secure-env-tool
npm install
npm link
```

## 📖 Usage

### 🎮 Interactive Mode

Launch the beautiful interactive interface:

```bash
hidenv
```

**What you'll see:**

```
 _   _ _     _ _____ _   ___     __
| | | (_) __| | ____| \ | \ \   / /
| |_| | |/ _` |  _| |  \| |\ \ / /
|  _  | | (_| | |___| |\  | \ V /
|_| |_|_|\__,_|_____|_| \_|  \_/

? What do you want to do? (Use arrow keys)
❯ 🔒 Encrypt .env
  🔓 Decrypt .env

? Enter your secret key: [hidden]
⠋ Encrypting...
✔ File encrypted as .env.enc
```

### ⚡ Command Line Mode

For automation and scripts:

#### 🔒 Encrypt a .env file

```bash
# Interactive password prompt
hidenv --e
# Output: ✔ File encrypted as .env.enc

# Direct password (not recommended for production)
hidenv --e mypassword
```

#### 🔓 Decrypt a .env.enc file

```bash
# Interactive password prompt
hidenv --d
# Output: ✔ File decrypted as .env

# Direct password (not recommended for production)
hidenv --d mypassword
```

#### 📚 Show help

```bash
hidenv --help
```

## 🧪 Quick Test & Verification

Want to verify everything works correctly? Follow these simple steps:

### 🚀 Basic Test

```bash
# 1. Create a test .env file
echo "TEST_API_KEY=secret123" > .env
echo "TEST_PASSWORD=mypassword" >> .env

# 2. Encrypt with a test password
hidenv --e testpass123

# 3. Verify .env.enc was created
ls -la *.enc

# 4. Test decryption
hidenv --d testpass123

# 5. Verify content is restored
cat .env
# Should show:
# TEST_API_KEY=secret123
# TEST_PASSWORD=mypassword
```

### 🔒 Security Test

```bash
# Test with wrong password (should fail)
hidenv --d wrongpassword
# Expected: ✖ Error: Failed to decrypt. Check your password.

# Test with correct password (should work)
hidenv --d testpass123
# Expected: ✔ File decrypted as .env
```

### 🎮 Interactive Mode Test

```bash
# Launch interactive mode
hidenv

# Follow the prompts:
# 1. Choose "🔒 Encrypt .env" or "🔓 Decrypt .env"
# 2. Enter your password when prompted
# 3. Watch the beautiful spinner animation!
```

## 🔧 How it Works

### 📊 Visual Process Flow

```
┌─────────────────────────────────────────────────────────────────┐
│                        ENCRYPTION PROCESS                       │
├─────────────────────────────────────────────────────────────────┤
│ 1. Read .env file     │ 2. Generate Salt    │ 3. Derive Key      │
│    ┌─────────────┐    │    ┌─────────────┐   │   ┌─────────────┐  │
│    │ API_KEY=123 │    │    │ Random 16B  │   │   │ scrypt(pwd) │  │
│    │ DB_PASS=xyz │ ──▶│    │ Salt        │──▶│   │ + salt      │  │
│    └─────────────┘    │    └─────────────┘   │   └─────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│ 4. Generate IV        │ 5. Encrypt Data     │ 6. Save .env.enc   │
│    ┌─────────────┐    │    ┌─────────────┐   │   ┌─────────────┐  │
│    │ Random 16B  │    │    │ AES-256-GCM │   │   │ Salt+IV+    │  │
│    │ IV          │ ──▶│    │ Encryption  │──▶│   │ Tag+Data    │  │
│    └─────────────┘    │    └─────────────┘   │   └─────────────┘  │
└─────────────────────────────────────────────────────────────────┘
```

### Encryption Process

1. 📁 **Read**: Parses your `.env` file preserving comments and formatting
2. 🧂 **Salt**: Generates a cryptographically random 16-byte salt
3. 🔑 **Key Derivation**: Uses scrypt with high cost parameters (N=16384, r=8, p=1)
4. 🎲 **IV Generation**: Creates a random 16-byte initialization vector
5. 🔒 **Encrypt**: Uses AES-256-GCM for authenticated encryption
6. 📦 **Package**: Combines all components into a binary `.env.enc` file

### Decryption Process

1. 📖 **Read**: Opens and validates the `.env.enc` file format
2. 🔍 **Extract**: Separates salt, IV, auth tag, and encrypted data
3. 🔑 **Key Derivation**: Recreates the key using your password and extracted salt
4. 🔓 **Decrypt**: Uses AES-256-GCM to decrypt and verify integrity
5. ✅ **Verify**: Validates authentication tag to ensure no tampering
6. 💾 **Save**: Writes the decrypted content back to `.env`

## 🛡️ Security Features

- **AES-256-GCM**: Industry-standard authenticated encryption
- **scrypt**: Memory-hard key derivation function (resistant to brute-force)
- **Random Salt**: Prevents rainbow table attacks
- **Random IV**: Ensures unique ciphertext even with same plaintext
- **Authentication Tag**: Prevents tampering and ensures data integrity

## 🔒 Why Encrypt .env Files?

Environment files often contain sensitive information like:

- API keys
- Database passwords
- Secret tokens
- Configuration secrets

By encrypting these files, you can:

- ✅ Store them safely in version control
- ✅ Share them securely with team members
- ✅ Backup sensitive configurations
- ✅ Prevent accidental exposure

## ⚠️ Important Notes

- **Remember your password**: Without it, your encrypted data cannot be recovered
- **Backup strategy**: Keep secure backups of both encrypted files and passwords
- **Version control**: Add `.env` to `.gitignore`, commit `.env.enc` instead
- **Team sharing**: Share passwords through secure channels only

### 🚀 Production Workflow

1. **Initial setup** with sensitive `.env`:

   ```bash
   # Create your .env file
   echo "API_KEY=secret123" > .env
   echo "DB_PASSWORD=supersecret" >> .env

   # Encrypt it
   hidenv --e mypassword

   # Add encrypted version to git
   git add .env.enc
   git commit -m "Add encrypted environment variables"
   ```

2. **Team member setup**:

   ```bash
   # Clone repository
   git clone <repo>
   cd <repo>

   # Decrypt (password shared securely)
   hidenv --d mypassword

   # Now you have the .env file ready
   ```

3. **Updating secrets**:

   ```bash
   # Edit .env file
   nano .env

   # Re-encrypt
   hidenv --e mypassword

   # Commit updated encrypted file
   git add .env.enc
   git commit -m "Update environment variables"
   ```

## 🎯 Real-World Examples

### Example 1: Node.js API Project

**Before (insecure):**

```bash
# .env file in your repository (❌ DANGEROUS)
API_KEY=sk-abc123def456
DATABASE_URL=postgresql://user:pass@host:5432/db
JWT_SECRET=my-super-secret-key
STRIPE_SECRET=sk_test_123456789
```

**After (secure):**

```bash
# 1. Encrypt your secrets
hidenv --e

# 2. Only commit the encrypted version
git add .env.enc
git commit -m "Add encrypted environment variables"

# 3. Add .env to .gitignore
echo ".env" >> .gitignore
```

### Example 2: Team Collaboration

**Team Lead:**

```bash
# Share the encrypted file via git
git add .env.enc
git commit -m "Add team environment variables"
git push origin main

# Share password securely (Slack DM, encrypted message, etc.)
# Password: "MyTeamSecurePass2024!"
```

**Team Member:**

```bash
# Clone and decrypt
git clone https://github.com/company/project.git
cd project
hidenv --d  # Enter shared password
npm install
npm start  # Environment ready! 🚀
```

### Example 3: Multiple Environments

```bash
# Development environment
cp .env.dev .env
hidenv --e devpassword
mv .env.enc .env.dev.enc

# Production environment
cp .env.prod .env
hidenv --e prodpassword
mv .env.enc .env.prod.enc

# Deploy to production
hidenv --d prodpassword  # Creates .env from .env.enc
docker build -t myapp .
```

## 🔍 File Format Deep Dive

### Binary Structure of .env.enc

```
┌──────────────────────────────────────────────────────────────┐
│                    .env.enc File Structure                   │
├──────────────────────────────────────────────────────────────┤
│ Magic Header  │ Version │ Salt (16B) │ Length │ Encrypted    │
│    "hidenv"     │   0x01  │  Random    │  4B    │ Content      │
│    (4 bytes)  │ (1 byte)│            │        │ (Variable)   │
└──────────────────────────────────────────────────────────────┘
```

**Why this format?**

- 🔍 **Magic Header**: Identifies the file type instantly
- 📊 **Version**: Allows future format updates
- 🧂 **Salt**: Each encryption uses a unique salt
- 📏 **Length**: Prevents buffer overflow attacks
- 🔒 **Content**: Your encrypted environment variables

## 🚨 Security Best Practices

### ✅ DO's

- ✅ Use strong, unique passwords (12+ characters)
- ✅ Store `.env.enc` in version control
- ✅ Share passwords through secure channels
- ✅ Backup both encrypted files and passwords
- ✅ Rotate passwords periodically
- ✅ Use different passwords for different environments

## 🐛 Troubleshooting

### Common Issues

**❓ "File not found" error**

```bash
# Make sure you're in the right directory
ls -la | grep env

# Check if file exists
hidenv --help  # Should show available options
```

**❓ "Invalid password" error**

```bash
# Password is case-sensitive, try again carefully
hidenv --d

# Check if .env.enc is corrupted
file .env.enc  # Should show "data"
```

**❓ "Permission denied" error**

```bash
# Fix file permissions
chmod 644 .env.enc
chmod 600 .env  # After decryption
```

### 🧪 Debug Commands

```bash
# Verify the tool is working correctly
node bin/cli.js --help

# Test with a simple example
echo "DEBUG_TEST=working" > .env
node bin/cli.js --e debug123
node bin/cli.js --d debug123
cat .env  # Should show: DEBUG_TEST=working

# Check file formats
ls -la .env*
# Should show both .env and .env.enc files

# Test error handling
node bin/cli.js --d wrongpassword
# Should show: ✖ Error: Failed to decrypt. Check your password.
```

### Getting Help

- 📖 Run `hidenv --help` for usage information
- 🐛 Check file permissions and current directory
- 🔑 Verify password is correct (case-sensitive)
- 📁 Ensure `.env` or `.env.enc` files exist

### Contributing

We welcome contributions! Here's how you can help:

- 🐛 **Report bugs** on GitHub Issues
- 💡 **Suggest features** via GitHub Discussions
- 🔧 **Submit pull requests** with improvements
- 📖 **Improve documentation** and examples
- ⭐ **Star the project** to show support

## �📄 License

MIT License - see LICENSE file for details

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

<div align="center">

**Made with ❤️ by erik**

_Keep your secrets safe! 🔐_

[![GitHub stars](https://img.shields.io/github/stars/username/secure-env-tool.svg?style=social&label=Star)](https://github.com/xErik444x/hidenv)

</div>