---
name: dot-vault
description: Encrypt and decrypt .env files with a password. Drop your real .env, get an .env.vault file safe to commit. Decrypt on a teammate's machine with the same password. AES-256-GCM via the cryptography library — strong + standard. Optional --rotate to change the password without exposing plaintext. Use when the user asks to "encrypt my .env", "share secrets safely", "vault my env", or doesn't want to use a SaaS like dotenv-vault.com.
---


# dot-vault

Encrypted `.env` management. Local-first, no SaaS. Drop your real `.env`, get a safely-committable `.env.vault` file. Anyone with the password can decrypt.

## How it works

- **Cipher:** AES-256-GCM (authenticated encryption — tamper-evident)
- **KDF:** PBKDF2-HMAC-SHA256, 200,000 iterations, 16-byte random salt
- **Nonce:** 12 random bytes per encryption (never reused)
- **Envelope format (`.env.vault`):**
  ```
  version: 1
  salt: <hex>
  nonce: <hex>
  ciphertext: <base64>
  ```

## Usage

```bash
# Encrypt .env -> .env.vault (prompts for password)
python3 scripts/vault.py lock --in .env

# Decrypt .env.vault -> .env
python3 scripts/vault.py unlock --in .env.vault

# Print plaintext to stdout instead of writing a file
python3 scripts/vault.py unlock --in .env.vault --stdout

# Rotate password (re-encrypt with new password, no plaintext on disk)
python3 scripts/vault.py rotate --in .env.vault

# Pass password non-interactively (CI use)
python3 scripts/vault.py lock --in .env --password "$VAULT_PASSWORD"
```

## Workflow

1. `python3 scripts/vault.py lock --in .env` — produces `.env.vault`
2. Add `.env` to `.gitignore`, commit `.env.vault`
3. Teammate clones repo, runs `python3 scripts/vault.py unlock --in .env.vault`
4. To rotate: `rotate` subcommand — re-keys without ever writing plaintext to disk

## Security notes

- AES-256-GCM provides both confidentiality and integrity — modified ciphertext won't decrypt
- Password strength matters — PBKDF2 200k iters slows brute force but a weak password is still weak
- Salt + nonce are stored in the envelope (safe — they're not secret, just non-reusable)
- Never commit `.env` (plaintext). Always commit `.env.vault`
- If you lose the password, the file is unrecoverable — there's no backdoor

## Why not dotenv-vault.com?

This is the same primitive without trusting a SaaS. Your secrets never leave your machine. No account, no API, no dependency on someone else's uptime.