@instant.dev/encrypt v0.0.7

Simple encryption for Environment variables

Encrypt environment variables

This package provides simple encryption / decryption methods, specialized for managing .env plaintext files in deployments, to prevent plaintext storage on your web server. This is only meant to prevent an attacker with filesystem access from reading your secrets; it's up to you to store the encryption secret, initialization vector (iv) and method separately. We recommend using your cloud hosts manual environment variable management to store __ENV_ENCRYPTION_SECRET, __ENV_ENCRYPTION_IV and __ENV_ENCRYPTION_METHOD which are used to decrypt the encrypted file.

Note: If you store the encryption secret, iv and method in plaintext as part of environment variables, then the attack surface area is anyone with administrative access to your server environment or the ability to execute code. This encryption is only meant to prevent those with filesystem access from reading your secrets.

How it works

We create an alternate .env file that looks like this;

__ENC_NzZjZGU0MjQxYmRlNTFiMjAxYjcwYmNhOThlNjhlNGU_0=MWU0MGQxODYwOTA0ZWI5Yjk0ZjU0OTI0Y2ZkZjQ0YWE_0
__ENC_MzRkY2ZlZWQxNDU3NGNmMGVmOTMxZDRiNTUzNTE3ZDU_0=Y2M0MGM0OGQ3MjNhYTE1YTgzMzIxZmFjZDc3MGM5Mjk_0
__ENC_OTI5NzA5NDNjMzM1M2NkZGNiOTk3MmI5Mjc5MmE4NzU_0=MDExZDU5Mjk4ZjZjOTQwNDYxODdmMTI3ZmE3NTU3N2E_0

These variables should then be loaded into process.env either using dotenv or the Node 20 built-in env loader. They can then be decrypted on process boot via:

const et = new EncryptionTools();
et.decryptProcessEnv(process.env);

And that's it! You'll want to make sure __ENV_ENCRYPTION_SECRET, __ENV_ENCRYPTION_IV and __ENV_ENCRYPTION_METHOD are set in process.env available on boot. The instant.dev deployment tools, @instant.dev/deploy will do this automatically.

Encrypting env vars while deploying:

const EncryptionTools = require('@instant.dev/encrypt');
const et = new EncryptionTools();

// When deploying to "staging" environment
const encryptResult = et.encryptEnvFileFromPathname('.env.staging');
// encryptResult.file is the file buffer
addToPackagedFiles('.env', encryptResult.file);
// encryptResult.env contains:
// __ENV_ENCRYPTION_SECRET: "..."
// __ENV_ENCRYPTION_IV: "..."
// __ENV_ENCRYPTION_METHOD: "..."
updateEnvVars(encryptResult.env);

Then decrypting server-side, if vars are store in .env:

const dotenv = require('dotenv');
dotenv.config();
et.decryptProcessEnv(process.env);

Acknowledgements

Special thank you to Scott Gamble who helps run all of the front-of-house work for instant.dev 💜!