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

# 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.