secure-env-vault Core

This package contains the core encryption and decryption logic (AES, PBKDF2, vault file format, etc.).

• src/crypto/: Cryptography utilities
• src/vault/: Vault file format and validation

Vault Format (v2)

• Encryption: AES-128-CBC
• Key Derivation: PBKDF2 (100,000 iterations, random salt)
• Salt: Randomly generated per vault, stored in the vault file
• Vault file:

{
  "version": 2,
  "salt": "...hex...",
  "secrets": {
    "API_KEY": { "value": "...encrypted...", "version": 1 },
    ...
  }
}

Secret Versioning

• Each secret in the vault is stored as an object with an encrypted value and a version number:

{
  "version": 2,
  "salt": "...hex...",
  "secrets": {
    "API_KEY": { "value": "...encrypted...", "version": 1 },
    ...
  }
}

• Benefits:
  • Enables per-secret key rotation in the future (rotate only one secret without re-encrypting the whole vault)
  • Supports rollback and audit trails for secret changes
  • Lays the foundation for advanced secret management features

Security Benefits

• PBKDF2 makes brute-force attacks much harder by using a strong, slow key derivation function.
• Each vault has a unique salt, so the same password produces different keys for different vaults.
• Secrets are never stored in plaintext.

Migration from v1

• If your vault does not have a salt field or has version: 1, re-encrypt it with the latest CLI:

npx secure-env encrypt .env .env.vault <password>

• All SDKs and loaders will warn if an old vault is detected.