enveloper

enveloper is a small, simple utility to encrypt secrets.

Installation

npm install enveloper

Example

Encrypt a value using a secret key:

> enveloper encrypt "this is a secret" --key "this is the secret key"
aes-256-gcm::sha256::base64::DYMNOOor7pRJduKneKn9dw==::MDZZYhhep3HSN9lkIXh+HQ==::l9KDBsxf6apQK501wADJgQ==

Set a secret into an envelope.json in your project:

> enveloper set my.secret "this is a secret" --key "this is the secret key"
> cat envelope.json
{
    "my": {
        "secret": "aes-256-gcm::sha256::base64::DYMNOOor7pRJduKneKn9dw==::MDZZYhhep3HSN9lkIXh+HQ==::l9KDBsxf6apQK501wADJgQ=="
    }
}

Encrypt another secret for your dev environment:

> enveloper set dev.my.secret "this is a secret for the dev environment" --key "this is the secret key for dev"
> cat envelope.json
{
    "my": {
        "secret": "aes-256-gcm::sha256::base64::DYMNOOor7pRJduKneKn9dw==::MDZZYhhep3HSN9lkIXh+HQ==::l9KDBsxf6apQK501wADJgQ=="
    },

    "dev": {
        "my": {
            "secret": "aes-256-gcm::sha256::base64::dIXProAFONjMle5n/CaIbw==::Kv+0ad4pbGVcJyII0FgZstT/k1nQqI9n+/rhgahr7ht/LSKWIuhcrw==::Vu0QVhlZFlSa3MKTW0ZeXA=="
        }
    }
}

Read a secret from your envelope.json via the command line:

> enveloper get my.secret --key "this is the secret key"
this is a secret

Get the secrets back out via the API (assuming NODE_ENV is 'dev' and we put our secrets into environment variables):

const enveloper = require( 'enveloper' );

const secrets = await enveloper.get( {
    secrets: [
        'my.secret',
        'my.deeper.secret'
    ],
    key: process.env.ENVIRONMENT_SECRET_KEY
} );

// secrets:
// {
//     "my": {
//         "secret": "this is a secret for the dev environment",
//         "deeper": {
//             "secret": "foo"
//         }
//     }
// }

API

get( { secrets: <mixed array of strings, path arrays, objects>[, key: ] } )

gets the given set of secrets

example

const enveloper = require( 'enveloper' );

const secrets = await enveloper.get( {
    secrets: [
        'test',
        'foo.bar.baz', // nested secret with dot notation
        [ 'foo', 'bar', 'yak' ], // nested secret in array notation
        { path: 'foo.another', key: 'separate key for foo.another' }, // object secret with associated key
        { path: 'foo.yet.another' } // object secret, equivalent to a string/array secret
    ],
    key: 'this is the key for most of the secrets'
} );

// secrets:
// {
//     "test": "this is the test secret",
//     "foo": {
//         "bar": {
//             "baz": "hi!",
//             "yak": "I'll eat anything!"
//         },
//         "another": "another secret in foo!",
//         "yet": {
//             "another": "yet another secret, deeper in foo!"
//         }
//     }
// }

envelope.json

By default, .get() will search up the directory tree for an envelope.json

The envelope.json file should contain string-based enveloper secrets, which can optionally be put into environments, eg:

{
    "dev": {
        "test": "aes-256-gcm::sha256::base64::ugsXgVN/3Gag0xI5wVvHjA==::tMsv2lCHhbFhD4NVUJ25Sm+muloURpdJfbM8a47LTQdP::nTY7C5a0u/4BmJwh3XXv0Q=="
    },

    "qa": {
        "test": "aes-256-gcm::sha256::base64::C86/3u+gQ4cyDAsK0qsG3g==::jb3Q5qNde6k1ATeP1+q7ly7/fspu/HHRODoLEryPn+k=::tQ86omDo71EyWRoD00UNmg=="
    },

    "prod": {
        "test": "aes-256-gcm::sha256::base64::1pCv3GoJQ2ZxiHYSKL77/Q==::KnnAxnjFFVJJf4sYij57Ak+S2SB2MC7FUJ64OjhL0wwgaw==::UOTl35IeueVRVpsBiZrUkQ=="
    },

    "shared_across_environments": "aes-256-gcm::sha256::base64::VYZleBk6O808v5ucdDh2Dg==::QhhHWfdYJNKU79a8LSASvqhsq305Cs8YiAQ=::FLTn1KA51UARf+Pj4CoYuQ=="
}

You can override the filename or the starting directory, eg:

const secrets = await enveloper.get( {
    secrets: [
        'test',
        'other'
    ]
    key: 'this is the key for the test secret',
    filename: 'my_envelope.json',
    directory: '/some/starting/directory'
} );

seal( secret[, options ] )

'seals' (encrypts) the given secret.

options

option	default	description
key	auto generated	the key to use for encryption
algorithm	aes-256-gcm	encryption algorithm to use, which must support an initialization vector and an auth tag
key_hash_algorithm	sha256	hashing algorithm for the key
input_encoding	utf8	input encoding of the secret
output_encoding	base64	output encoding for the encrypted value
iv	auto generated	initialization vector for the encryption algorithm

example

const enveloper = require( 'enveloper' );

const result = enveloper.seal( 'foo' );

// result:
// {
//     encrypted: 'k6Dp',
//     tag: '4ibYKY3u0CzgSeXkRmipuQ==',
//     key: 'twWq+Ah/UwCbOwYwx/tHL6Q5VurE2vGmzXkjczB+62bOGtUoppTfMF8Ukm0uRL0Tk8vo+UhW32H46qVKCxg2bQ==',
//     algorithm: 'aes-256-gcm',
//     key_hash_algorithm: 'sha256',
//     input_encoding: 'utf8',
//     output_encoding: 'base64',
//     iv: 'Zuv+EphpT8Kkjh9acWAMbQ=='
// }

open( options )

'opens' (decrypts) the given secret using the specified options

options

option	required	description
encrypted	yes	the encrypted value to decrypt
key	yes	the key to use for decryption
iv	yes	initialization vector
tag	yes	the auth tag
algorithm	no	encryption algorithm to use, assumes default
key_hash_algorithm	no	hashing algorithm for the key, assumes default
input_encoding	no	input encoding of the secret, assumes default
output_encoding	no	output encoding for the encrypted value, assumes default

example

const enveloper = require( 'enveloper' );

const result = enveloper.open( {
    encrypted: 'k6Dp',
    key: 'twWq+Ah/UwCbOwYwx/tHL6Q5VurE2vGmzXkjczB+62bOGtUoppTfMF8Ukm0uRL0Tk8vo+UhW32H46qVKCxg2bQ==',
    iv: 'Zuv+EphpT8Kkjh9acWAMbQ==',
    tag: '4ibYKY3u0CzgSeXkRmipuQ=='
} );

// result:
// {
//     decrypted: 'foo',
//     algorithm: 'aes-256-gcm',
//     key_hash_algorithm: 'sha256',
//     input_encoding: 'utf8',
//     output_encoding: 'base64',
//     encrypted: 'k6Dp',
//     key: 'twWq+Ah/UwCbOwYwx/tHL6Q5VurE2vGmzXkjczB+62bOGtUoppTfMF8Ukm0uRL0Tk8vo+UhW32H46qVKCxg2bQ==',
//     iv: 'Zuv+EphpT8Kkjh9acWAMbQ==',
//     tag: '4ibYKY3u0CzgSeXkRmipuQ=='
// }

to_string( options )

converts a .seal() result to a string

example

const enveloper = require( 'enveloper' );

const sealed = enveloper.seal( 'foo' );

const str = enveloper.to_string( sealed );

// str:
// aes-256-gcm::sha256::base64::Zuv+EphpT8Kkjh9acWAMbQ==::k6Dp::4ibYKY3u0CzgSeXkRmipuQ==

from_string( options )

parses a string into a set of enveloper options

example

const enveloper = require( 'enveloper' );

const sealed = enveloper.seal( 'foo' );

const str = enveloper.to_string( sealed );

const sealed_from_string = enveloper.from_string( str );

// sealed_from_string:
// {
//     algorithm: 'aes-256-gcm',
//     key_hash_algorithm: 'sha256',
//     output_encoding: 'base64',
//     iv: 'Zuv+EphpT8Kkjh9acWAMbQ==',
//     encrypted: 'k6Dp',
//     tag: '4ibYKY3u0CzgSeXkRmipuQ=='
// }

Contributing

Pull requests are very welcome! Just make sure your code:

1. Passes eslint given the included .eslintrc.json

2. Follows the same style as existing code

3. Has associated tests