Encrypted .env Files

varsafe encrypts .env files by default, so they can be safely committed to git or stored on disk without exposing secrets.

How It Works

Each environment has a keypair managed by varsafe. When you run varsafe export, each value is individually encrypted using that environment's public key. The private key is stored server-side, encrypted by KMS — it never exists in plaintext in the database.

Cryptography: ECIES with X25519 key exchange, HKDF-SHA256 key derivation, and AES-256-GCM symmetric encryption. Each value gets its own ephemeral keypair for forward secrecy.

Quick Start

# Export an encrypted .env file
varsafe export -p my-api -e development -o .env

# The file is safe to commit
git add .env

# Decrypt and inject into a command
varsafe run --env-file .env -- npm run dev

File Format

An encrypted .env file looks like this:

#@varsafe/v1/ek_a1b2c3d4
DATABASE_URL="varsafe:v1:base64url-encoded-ciphertext..."
API_KEY="varsafe:v1:base64url-encoded-ciphertext..."

• The header comment (#@varsafe/v1/ek_...) identifies the keypair used for encryption
• Each value is prefixed with varsafe:v1: followed by the encrypted payload
• The public key is not stored in the file — it's fetched from the API when needed

Workflows

Local Development

# One-time: export encrypted .env
varsafe export -p my-api -e development -o .env

# Daily: run with decryption
varsafe run --env-file .env -- npm run dev

Add .env to your repo — new team members clone and run without needing to configure secrets manually.

CI/CD

CI pipelines should use --plain since secrets are ephemeral:

# CI: plaintext to tmpfs (never touches persistent disk)
varsafe export --plain --tmpfs -o app.env
docker compose --env-file /dev/shm/app.env up -d
rm -f /dev/shm/app.env

Or skip .env files entirely:

varsafe run -p my-api -e production -- ./deploy.sh

Multiple Environments

varsafe export -p my-api -e development -o .env
varsafe export -p my-api -e staging -o .env.staging

# Run with specific file
varsafe run --env-file .env.staging -- npm run dev

Merging Sources

API secrets and env-file secrets can be combined. Env-file values take priority:

varsafe run -p my-api -e dev --env-file .env.local -- npm run dev

Key Rotation

Auto-Rotation

When a team member is removed, varsafe automatically rotates keypairs for every environment whose private key they accessed. This ensures removed members can't decrypt future .env files, even if they retained a copy.

Configure per team:

• auto (default) — rotate on member removal
• manual — no automatic rotation

Manual Rotation

Keypair status and manual rotation are managed from the dashboard under Encryption Keys. You can see which environments have active keypairs, whether any removed members had key access, and rotate with one click.

After rotation, existing encrypted .env files are automatically re-encrypted on next use with varsafe run --env-file.

Plaintext Export

For cases where encryption isn't needed:

# Plaintext .env
varsafe export --plain -o .env

# JSON and YAML are always plaintext
varsafe export -f json -o secrets.json
varsafe export -f yaml -o config.yaml

WARNING

Plaintext .env files should be gitignored. Only encrypted .env files are safe to commit.

Security Properties

• At rest: Values encrypted with AES-256-GCM; private key KMS-encrypted in database
• Forward secrecy: Each value uses an ephemeral keypair — compromising one value doesn't help decrypt others
• Key exposure tracking: Audit log records every private key access, enabling targeted rotation
• Transparent re-encryption: Stale files are silently upgraded when the keypair rotates