envcrypt

Javascript CLI to encrypt/decrypt sensitive configuration, and add them to the ENV.

how it works

The purpose of envcrypt is to commit your sensitive environment variables in a safe manner in a way that allows you to track configuration changes over time. Its CLI behaves a lot like Rails 5.1's encrypted secrets for editing and managing these values.

In addition to the cli tool, there are three important components to the setup:

• .envcrypt.key: A gitignored file containing aes256 encryption key used to encrypt/decrypt the secrets. This key can also be supplied via an environment variable ENVCRYPT_KEY.
• secrets.json: The encrypted secrets, grouped by their server environment.
• config.json: The plain-text config values, grouped by their server environment.

Let's jump in and get setup.

getting started

First, you'll need to add envcrypt to your node application. This will install the envcrypt package from the private npm registry.

$ npm install @codeverse/envcrypt

After it has been installed, we'll need to run the setup command.

$ envcrypt setup

After running this command, you'll have 3 new files in your project's root directory, .envcrypt.key, secrets.json and config.json. They'll look like this to start:

.envcrypt.key

332d18e58c86a9cca525c7f93f47b58e016a9befe2b

secrets.json

{ 
  "production": {},
  "qa": {}
}

config.json

{
  "production": {},
  "qa": {},
  "development": {},
  "test": {}
}

Note - config.json contains "development" and "test" blocks, but secrets.json does not. Since all of the environments are encrypted with the same key, an exposed encryption key in development would unlock your production secrets as well. In order to prevent accident leaks, we recommend you keep your development/test values inside config.json. There is also a gitignore'd file .envcrypt.key that would contain your key, which will be pulled in by envcrypt to set the key.

Now that you have these files created, you'll need to populate them with your configurations. You can edit config.json with any text editor to store non-sensitive environment variables, like URLs or ports. In order to edit the secrets.json, you'll need to use the CLI to decrypt/encrypt the values.

$ envcrypt edit

This will open up an $EDITOR (defaults to vim) to edit secrets.json, but in a plain-text fashion. If there is already encrypted values in the file, it will decrypt them before opening the editor. Once you've finished editing the JSON and close the editor window, it will re-encrypt them and write it to secrets.json.

Let's say you want to quickly check all of the environment variables that envcrypt will add to your project's process.env.

$ envcrypt read

This will output the keys with decrypted values from secrets.json, as well as the plain-text configuration values from config.json for each of the environments, "production", etc.

Lastly, you'll probably need to start your server, or run your tests with these encrypted variables. When running envcrypt without our predefined commands, it will assume you are trying to use it as a pre-command to load the environment into the a subsequent command.

$ envcrypt -e (environment) (command)
# runs any command with the environment values decrypted from secrets.json, the plain-text configuration placed into process.env

When it's time to run the tests, or spin up the server, you'll likely need access to those encrypted values. You can use the envcrypt as a pre-command before your test or server scripts, like below.

setup precommand in package.json

{
  "name": "my-awesome-envcrypted-application",
  ...
  "scripts": {
    "start": "envcrypt node dist/server.js",
    "test": "envcrypt --config test jest",
    ...
  },
  ...
}

and then in your shell

# run the tests
npm test

# in orderto pass arguments to envcrypt, add them after a --
$ npm start -- -c production

storage

envcrypt splits the configuration between two files; a plain-text one for basic values (like URLs and ports), and an encrypted one for sensitive information (api keys, application ids/secrets, etc). This pattern follows the Rails' way™, much like secrets.yml / secrets.yml.enc.

When you run envcrypt setup, these config files (config.json and secrets.json) will be generated for you. You can edit and manage config.json using any editor, but for secrets.json, you'll need to use encrypt edit to change the values. Below is an example of the resulting output of the encryption in the secrets.json file.

{
  "production": {
    "FOO": "asfasf123r123e4qdfwfqwfqr12r12r1r=",
    "BAR": "123qsdsdbdq0e4y34tfsfgsdfbsdgsdg23r423r3="
  },
  "beta": {
    "FOO": "vsdfgkertrktertpekt235023rqdfm124=",
    "BAR": "asf1242rtfdgnvhjr5y745ytfdfsdfwq23rewdfa="
  }
}

The envcrypt runner will combine the values in secrets.json and config.json for the given environment, and stick the key/value pairs into process.env for your application to pull from.