Yemaya provides built-in encryption for sensitive environment variables using AES-256-GCM authenticated encryption.
Overview#
Sensitive values like API keys, database passwords, and secrets can be encrypted
at rest in your .env files. The configuration loader automatically decrypts
these values at runtime using a master key.
Quick Start#
1. Generate a Master Key#
pnpm env:generate-key
This outputs a secure 256-bit key encoded in base64. Store this key securely.
2. Set the Master Key#
Choose one of these methods:
Environment Variable (recommended for development):
export YEMAYA_MASTER_KEY="your-generated-key"
File (recommended for production):
echo "your-generated-key" > /path/to/master.key
chmod 600 /path/to/master.key
export YEMAYA_MASTER_KEY_FILE="/path/to/master.key"
Docker Secrets (recommended for Swarm/Kubernetes):
echo "your-generated-key" | docker secret create yemaya_master_key -
3. Encrypt Your Environment File#
YEMAYA_MASTER_KEY="your-key" pnpm env:encrypt .env.production
This encrypts all sensitive values in place. Sensitive keys are detected automatically based on common patterns (PASSWORD, SECRET, KEY, TOKEN, etc.).
4. Use Encrypted Values#
The configuration loader automatically decrypts values at runtime:
import { loadConfig } from '@yemaya/core';
const config = loadConfig();
// config.database.url is automatically decrypted
CLI Commands#
Encrypt a File#
# Encrypt .env (default)
pnpm env:encrypt
# Encrypt specific file
pnpm env:encrypt .env.production
# Output to different file
pnpm env:encrypt .env.production -o .env.production.encrypted
Decrypt a File#
# Decrypt .env.encrypted (default)
pnpm env:decrypt
# Decrypt specific file
pnpm env:decrypt .env.production
# Output to different file
pnpm env:decrypt .env.encrypted -o .env.local
Encrypt Single Value#
pnpm env:encrypt-value "my-secret-password"
# Output: ENC:v1:salt:iv:authTag:ciphertext
Decrypt Single Value#
pnpm env:decrypt-value "ENC:v1:..."
# Output: my-secret-password
Generate New Key#
pnpm env:generate-key
Encrypted Value Format#
Encrypted values use the format:
ENC:v1:<salt>:<iv>:<authTag>:<ciphertext>
ENC- Prefix identifying encrypted valuesv1- Format versionsalt- 32-byte salt for key derivation (hex)iv- 16-byte initialization vector (hex)authTag- 16-byte authentication tag (hex)ciphertext- Encrypted data (hex)
Sensitive Key Detection#
The following patterns are automatically detected as sensitive:
PASSWORDSECRETKEYTOKENCREDENTIALPRIVATEAPI_KEYACCESS_KEYSECRET_KEYAUTHDSNCONNECTION_STRING
Examples of matched keys:
DATABASE_URL(contains sensitive connection string)JWT_SECRETANTHROPIC_API_KEYREDIS_PASSWORDMINIO_SECRET_KEY
Programmatic Usage#
Encrypt Values#
import { encrypt, encryptEnvVars } from '@yemaya/core';
// Encrypt single value
const encrypted = encrypt('my-secret', { masterKey: 'your-master-key' });
// Encrypt multiple values
const encrypted = encryptEnvVars(
{ DATABASE_URL: 'postgres://...', APP_NAME: 'myapp' },
{ masterKey: 'your-master-key' }
);
// Only DATABASE_URL is encrypted (contains sensitive pattern)
Decrypt Values#
import { decrypt, decryptEnvVars, isEncrypted } from '@yemaya/core';
// Check if encrypted
if (isEncrypted(value)) {
const decrypted = decrypt(value, { masterKey: 'your-master-key' });
}
// Decrypt multiple values
const decrypted = decryptEnvVars(encryptedEnv, {
masterKey: 'your-master-key',
});
Get Master Key#
import { getMasterKey } from '@yemaya/core';
const key = getMasterKey(); // From env var or file
Security Considerations#
Key Storage#
- Never commit master keys to git
- Use different keys per environment (dev, staging, production)
- Rotate keys periodically using the secrets manager
- Use secret management services in production:
- Docker Swarm secrets
- Kubernetes secrets
- HashiCorp Vault
- AWS Secrets Manager
- GCP Secret Manager
Encryption Details#
- Algorithm: AES-256-GCM (authenticated encryption)
- Key Derivation: scrypt with N=16384, r=8, p=1
- Salt: 32 bytes, unique per encryption
- IV: 16 bytes, randomly generated
- Auth Tag: 16 bytes for integrity verification
Best Practices#
- Encrypt production secrets only - Development can use plaintext
- Audit encrypted files - Review what's encrypted with
git diff - Test decryption - Verify config loads correctly before deployment
- Backup keys securely - Use separate backup for master keys
- Log carefully - Ensure logs don't expose decrypted values
Troubleshooting#
"No master key provided"#
Set YEMAYA_MASTER_KEY environment variable or YEMAYA_MASTER_KEY_FILE.
"Decryption failed"#
- Verify you're using the correct master key
- Check the encrypted value format (should start with
ENC:v1:) - Ensure the value wasn't corrupted
"Invalid encrypted value format"#
The value doesn't match the expected ENC:v1:... format. It may be:
- Already decrypted
- Encrypted with an older/incompatible version
- Corrupted
Config validation fails after encryption#
Ensure the master key is available before loading config:
export YEMAYA_MASTER_KEY="your-key"
pnpm validate:env
Integration with Docker#
Development (docker-compose.yml)#
services:
api:
environment:
- YEMAYA_MASTER_KEY=${YEMAYA_MASTER_KEY}
Production with Secrets#
services:
api:
secrets:
- yemaya_master_key
environment:
- YEMAYA_MASTER_KEY_FILE=/run/secrets/yemaya_master_key
secrets:
yemaya_master_key:
external: true
Key Rotation#
To rotate the master key:
- Decrypt all files with the old key
- Generate a new key
- Re-encrypt all files with the new key
- Update secret storage with the new key
- Deploy the new key to all environments
# Using secrets manager
./scripts/secrets-manager.sh rotate yemaya_master_key