npm package: @sazzadur/envlock
Description: Encrypt and decrypt .env files safely for internal teams
Author: Sazzadur Rahman
Latest version: 1.0.1

# envlock

A minimal CLI tool to encrypt and decrypt `.env` files for trusted teams.

`envlock` helps prevent **accidental secret leaks in Git repositories** by encrypting environment files into `.env.lock*` files that are safe to commit.

This is a **local-first**, **password-based** solution intended for **small, trusted teams**.

---

## What's New in v1.0.1

### ⚠️ Breaking Change

- **New file extension**: Encrypted files now use `.env.lock*` instead of `.env.enc*`
- Run `envlock migrate` to upgrade existing projects (see [Migration Guide](#migrating-from-v0x-to-v100))

### New Commands

- **`envlock status`** - View encryption status of all environment files at a glance
- **`envlock diff`** - Compare local `.env` against encrypted version with masked values
- **`envlock rotate`** - Change encryption password without exposing secrets to disk
- **`envlock encrypt-all`** - Encrypt all `.env` files at once
- **`envlock decrypt-all`** - Decrypt all `.env.lock` files at once
- **`envlock migrate`** - Migrate from v0.x to v1.x

### New Features

- **CI/CD Support** - Use `ENVLOCK_PASSWORD` environment variable for automation
- **Password Strength Validation** - Warns about weak passwords during encryption
- **`--force` Flag** - Skip confirmation prompts for scripting and automation
- **`--help` Flag** - Detailed help for all commands

---

## Migrating from v0.x to v1.0.1

⚠️ **Breaking Change**: From v1.0.1 onwards, envlock uses `.env.lock*` instead of `.env.enc*` for encrypted files.

If you have existing `.env.enc*` files from a previous version, run:

```bash
envlock migrate
```

This will:

- Rename all `.env.enc*` files to `.env.lock*`
- Update your `.gitignore` patterns
- Preserve your encrypted content (no re-encryption needed)

For automated environments:

```bash
envlock migrate --force
```

---

## Installation

### Requirements

- Node.js 18 or higher
- npm

### Install globally

```bash
npm install -g @sazzadur/envlock
```

This installs the `envlock` command globally.

---

## Quick start

### 1. Initialize a project

```bash
envlock init
```

This will:

- Detect existing `.env*` files
- Ask which file to initialize if multiple exist
- Update `.gitignore` to ignore `.env` and `.env.*`
- Encrypt the selected file into `.env.lock*`
- Leave the original `.env*` file intact

---

### 2. Encrypt environment files

```bash
envlock encrypt
```

- Detects `.env` or `.env.*` files
- Prompts for file selection if multiple exist
- Creates a corresponding `.env.lock*` file
- Validates password strength

Example:

```
.env.dev → .env.lock.dev
```

---

### 3. Decrypt environment files

```bash
envlock decrypt
```

- Detects `.env.lock*` files
- Prompts for file selection if multiple exist
- Restores the original `.env*` file
- Asks for confirmation before overwriting existing files

---

### 4. Check encryption status

```bash
envlock status
```

Shows a table of all environment files and their encryption status:

- ✔ **Synced** - Local and encrypted files are in sync
- ⚠ **Needs Encrypt** - Local changes not yet encrypted
- ↓ **Needs Decrypt** - Encrypted file exists but no local copy
- ✖ **Unencrypted** - Local file has no encrypted version

---

### 5. Compare differences

```bash
envlock diff
```

Safely compare your local `.env` file against the encrypted version:

- Shows added, removed, and modified variables
- Values are masked for security
- Helps identify what changed before encrypting

---

### 6. Rotate passwords

```bash
envlock rotate
```

Change the encryption password on an existing `.env.lock*` file:

- Verifies current password
- Re-encrypts with new password
- Creates automatic backup during rotation

---

### 7. Batch operations

```bash
envlock encrypt-all
envlock decrypt-all
```

Encrypt or decrypt all environment files at once using a single password.

---

## Command-line options

### --force, -f

Skip all confirmation prompts. Useful for automation:

```bash
envlock encrypt --force
envlock decrypt-all -f
```

### --help, -h

Show help information:

```bash
envlock --help
envlock encrypt --help
```

---

## CI/CD Integration

For automated pipelines, set the `ENVLOCK_PASSWORD` environment variable:

```bash
export ENVLOCK_PASSWORD="your-secret-password"
envlock decrypt-all --force
```

This allows non-interactive decryption in CI/CD environments.

**⚠️ Security note:** Ensure `ENVLOCK_PASSWORD` is stored securely in your CI/CD system's secret management (e.g., GitHub Secrets, GitLab CI Variables).

---

## Recommended workflow

1. Create `.env` or `.env.*` locally
2. Run `envlock init`
3. Commit `.env.lock*` and `.gitignore`
4. Share the password securely with the team
5. Teammates run `envlock decrypt` locally
6. After local changes, run `envlock encrypt`
7. Use `envlock status` to check sync state

⚠️ Never commit plaintext `.env` files.

---

## Security model

envlock uses:

- AES-256-GCM encryption
- scrypt key derivation
- Random salt and IV per encryption

Passwords are:

- Never stored
- Never logged
- Entered interactively

envlock protects against **accidental exposure**, not deliberate misuse.

---

## Supported platforms

- macOS
- Linux
- Windows (PowerShell or Windows Terminal recommended)

---

## Why envlock exists

Teams often end up with secrets scattered across:

- Slack messages
- Notion pages
- Old README files
- Someone’s local machine

envlock gives you a simple, repeatable workflow:

- Secrets stay out of Git
- Encrypted files can be committed
- Developers decrypt locally when needed

No servers. No dashboards. No lock-in.

---

## What envlock does

- Encrypts `.env` and `.env.*` files into `.env.lock*`
- Preserves environment suffixes  
  (`.env.prod → .env.lock.prod`)
- Supports multiple environment files
- Keeps plaintext `.env*` files local
- Automatically updates `.gitignore`
- Works on macOS, Linux, and Windows

---

## What envlock does NOT do

envlock is **not** a full secret management system.

It does NOT:

- Manage access control
- Provide audit logs
- Rotate secrets automatically
- Protect against malicious insiders
- Protect compromised machines

If the shared password is leaked, **all encrypted secrets are compromised**.

Use this tool only with **trusted teammates**.

---

## When NOT to use envlock

Do not use envlock if:

- You need strict access control
- You require audit trails
- You work with untrusted contractors
- You need compliance guarantees
- You manage highly sensitive production secrets

In those cases, use a dedicated secret management solution.

---

## Final note

envlock is designed to be boring, predictable, and safe.

If it ever feels clever, something is wrong.