Security and recovery

ramenv encrypts selected values at rest and avoids generating a decrypted .env file at runtime. It does not isolate processes or guarantee that decrypted values stay off disk. A process that can read both your vault and its keys can recover the secrets.

Encryption and key access

Encrypted values use AES-256-GCM with a fresh nonce per value and a secret: prefix in the vault. Encryption and vault-signing keys are separate. Workspaces share encryption keys per environment; each registered vault has a signing key.

Local keys are unencrypted in .ramenv.keys. Cloud ingredients store keys in the selected secret manager and keep version-pinned refs in .ramenv.keyrefs.toml. Cloud access control restricts who can fetch keys; an identity with access can still decrypt the vault.

Use --plaintext only for values you are comfortable exposing in Git.

Integrity and visible metadata

The vault HMAC uses HMAC-SHA256 over canonical environment data, including environment names, variable names, and stored values. ramenv verifies it before loading a vault.

Use CLI commands for environment-data changes. Manually editing a stored value or merging incompatible environment data can make the HMAC invalid.

The HMAC excludes validation rules, workspace metadata, and cloud key-reference files. Review those files and schema changes in code review. Anyone with the signing key can produce a valid HMAC; it authenticates with a shared key.

Visible vault information includes:

• Environment and variable names.
• Validation rules.
• Values explicitly stored as plaintext.
• Integrity metadata and encrypted value representations.

Commit the vault only after reviewing plaintext and metadata disclosure.

Runtime and terminal exposure

run decrypts in memory and injects values into the child’s process environment. It does not create a decrypted .env file, but the application, OS, debugger, logs, crash dumps, or another process with sufficient access may expose those values.

Onboarding leaves the source .env intact, and local keys remain on disk.

list and diff mask values by default, but masks may show portions. --reveal prints complete decrypted values. Do not rely on masking as a safe logging boundary.

Back up for recovery

Keep secure backups of keys and the corresponding vault versions. Losing an encryption key makes its encrypted values unrecoverable; reinitializing does not recreate the old key.

Cloud refs point to exact versions. Recovery requires those remote versions to remain available and readable, so retain the keys as well as the committed refs.

Rotation changes the key for current encrypted values. Older Git history needs its corresponding older keys. Environment removal may delete the whole cloud secret and all versions; check the provider’s retention rules before removing anything needed for recovery.

Respond to exposure

If raw keys or decrypted credentials were committed or logged:

1. Restrict access to the exposed material and investigate where it was copied.
2. Rotate affected application credentials with their owning systems. Re-encrypting the same leaked credential does not revoke it.
3. Rotate the relevant ramenv environment key and review all affected registered vaults.
4. Review signing-key exposure separately. Do not assume that rotating the encryption key replaces the signing key.
5. Untrack exposed files and handle copies in Git history, logs, artifacts, and backups according to your incident process.

A .gitignore entry does not remove tracked files or historic copies. Avoid putting real keys, credentials, or decrypted values in bug reports. Use troubleshooting to investigate without disclosing them.