ciphenv v3.0.2

Ciphenv

Ciphenv (Ciphered Env) is a simple CLI tool to encrypt/cipher your .env files using prefixes to indicate whether you want the value to be encrypted using a given secret.

• Ciphenv
  • Install
  • Usage
    • Encryption
      • At Runtime
      • Using the CLI
      • Encrypting Entire Files
    • Decryption
      • At Runtime
      • Using the CLI
      • Decrypting Entire Files
    • CLI Options

Install

npm install --save ciphenv

or

npm install -g ciphenv

Usage

Create one or many .env file(s) and add some values in following the dotenv pattern, e.g.

DB_HOST="localhost"
DB_USER="root"
DB_PASS="s1mpl32"

Encryption

At Runtime

To encrypt at runtime Ciphenv provides the encryptValue utility function.

/**
 * @param secret the secret used to encrypt the values.
 * @param value the value to encrypt
 * @returns the encrypted value
 */
function encryptValue(secret: string, value: string): string;

Here is an example of this usage:

import dotenv from "dotenv";
import { encryptValue } from "ciphenv";

function encrypt(someValue: string) {
  return encryptValue(process.env.SECRET, someValue);
}

Using the CLI

For the values that you want to be encrypted add a prefix of DEC: (which indicates it is decrypted) to the value. For example, taking the previous example and assuming the DB_PASS would want to be encrypted:

DB_HOST="localhost"
DB_USER="root"
DB_PASS="DEC:s1mpl32"

Then, all that is needed is to run:

$ npx ciphenv encrypt -F --secret superSecret

# `.env.enc` file created

and the output in the .env.enc file would be:

DB_HOST="localhost"
DB_USER="root"
DB_PASS="ENC:********"

Encrypting Entire Files

Ciphenv is also able to encrypt whole files through the use of another special prefix, being DEC_FILE_PATH: (path to the decrypted file). This can be especially useful for PEM keys and other multiline values that require encryption.

Following from the example above, the syntax would look like this:

DB_HOST="localhost"
DB_USER="root"
DB_PASS="DEC:s1mpl32"
PEM="DEC_FILE_PATH:./keys/super-secret.pem"

after encryption, the resultant .env file would end up as so:

DB_HOST="localhost"
DB_USER="root"
DB_PASS="ENC:********"
PEM="ENC:********"

Decryption

At Runtime

To decrypt at runtime Ciphenv provides two utility functions decryptValues and decryptValue.

/**
 * @param secret the secret used to encrypt the values
 * @param env the parsed output from `dotenv` for the specified `.env*` file
 * @returns the unencrypted env object (without the `DEC:` prefix on the values)
 */
function decryptValues(secret: string, env: { [key: string]: any }): { [key: string]: any };

/**
 * @param secret the secret used to encrypt the values.
 * @param value the value to decrypt
 * @returns the decrypted value (without the `DEC:` prefix)
 */
function decryptValue(secret: string, value: string): string;

Here is an example of this usage:

import dotenv from "dotenv";
import { decryptValues } from "ciphenv";

const config = decryptValues(process.env.SECRET, dotenv.config({ path: `.env.${NODE_ENV}.enc` }).parsed);

Using the CLI

To decrypt the encrypted .env file from the CLI you can then just run:

$ npx ciphenv decrypt -F --secret superSecret

# `.env.dec` file created

and the output would be:

DB_HOST="localhost"
DB_USER="root"
DB_PASS="DEC:s1mpl32"

Just remember to not commit the decrypted .env file(s)!

Here are .gitignore entries which could be used to avoid committing the decrypted .env files when using the default naming pattern:

.env.*
!.env.*.enc

Decrypting Entire Files

Decrypting entire files places the decrypted file path back in to the .env file like so:

DB_HOST="localhost"
DB_USER="root"
DB_PASS="DEC:s1mpl32"
PEM="DEC_FILE_PATH:./keys/super-secret.pem"

and also creates the super-secret.pem file with it's decrypted contents again.

The above occurs partly to avoid any issues with re-encrypting the decrypted .env file as the value would be multiline, but also to have the behaviour that you may expect, where something decrypted should match the original used during encryption.

CLI Options