mimosa-vault

Overview

Mimosa module which uses the vault project to generate passwords derived from a secret key. The intent of this module is to provide an easy way to generate passwords for various services without embedding the secrets in the project's source. It provides convenient way to re-derive all the secrets that a project needs in order to operate, without also requiring the syncing of an encrypted database.

Passwords are derived from a secret key and the derivation process can be controlled to specify the character set of the derived passwords. There is no encrypted database to keep in sync -- if you want to re-derive the same passwords in multiple places, sync only the secret key.

The module also makes passwords available to other mimosa modules -- the idea is that other mimosa modules which need to deal with things could take advantage of this same mechanism to gain access to credentials without needing to embed the credentials in the project source code or mimosa-config.

The module will transform project files with the magic extension '.vault.coffee' (or .js, or any other extension which compiles to .js) into file with the the derived passwords for the services listed in the .vault file. This is primarily useful for something like server-side code which needs to embed passwords for external services like database servers or external web apis. This module is also also useful for managing development/testing versions of client-side credentials (eg passwords for 'testing' accounts which may need to be made available to client-side code when running project test suites).

When this module is included, mimosa-vault will use a project specific 'password key' to transform any .vault.js or .vault.coffee files within the project's source javascript directory into either a json file or a commonjs module containing passwords derived from the key and conforming to any specified character class (in order to meet password character set/complexity requirements).

The algorithm used by the vault module to derive passwords ensures that knowledge of any generated passwords does not allow deriving other passwords which would be derived from the secret key.

If desired, the files that mimosa-vault outputs can themselves be encrypted with a specified encryptionKey. This allows deploying compiled code to sites without having to deploy the passwordKey -- deploying only the encryptionKey is required. The stanford javascript crypto library is used to perform the encryption.

Usage

Add 'vault' to your list of modules. That's all! Mimosa will install the module for you when you start up.

By default a key will be generated at .mimosa/vault/{project-name}.key if one does not already exist. Overwrite the key at any time. Copy the key from another host or location to allow mimosa-vault to re-generate the same secrets in multiple sites -- or use a unique key everywhere the code is deployed to get unique passwords for each code deployment.

Quick Start

1. install mimosa-vault into project directory (project not currently available from npm)
2. add 'vault' to your module list
3. create a .vault.coffee file listing some services which need passwords
4. run a mimosa build -- you've now generated a secret and a set of passwords from that secret
5. Set the passwords for the external services represented in your .vault.json to the passwords generated by vault
6. Use the .vault.json credentials in your code to access the service(s)

Share the key with anyone with whom you want to share the project's credentials, keep the key secret from anyone with whom you do not want to share the project's credentials.

Functionality

Describe the api's which need secrets as simple objects within your javascriptDir. For example:

assets/javascripts/some_secrets.vault.coffee

module.exports =
    "my_twitter_account": {"upper":1, "lower":0, revision:1}
    "my_development_couchdb_account": {}

mimosa-vault will compile this to:

public/javascripts/some_secrets.json

{
 "my_twitter_account":"DUITB66R0ATQOUVZ9W7F",
 "my_development_couchdb_account":"qdJdsasYMSn dHN4QcNr"
}

The secret shown above for 'my_twitter_account" is actually a unique cryptographic hash mapping (secret, "my_twitter_account", {"upper:1, "lower:0}) -> "derived secret" -- "derived secret" conforms to a character alphabet which contains at least one upper and no lower case characters.

module.exports = {
    "some_service_login": {upper: 1, dash:0}
}

{upper:1, dash:0} is passed to the underlying Vault call -- each key represents a character set and value of each key
should be a Number 0 or greater.  0 means no characters from that character set should appear in the password.  A
number greater than 1 specifies that at least that many characters from that character set should appear in the
password.

See the vault project for a description of the options which can be used to control the derived password's alphabet
https://github.com/jcoglan/vault

There is one extra option 'revision' which is processed by mimosa-vault rather than the underlying
vault module.  The value is appended to the value passed to the underlying vault -- , allowing one
to derive new passwords for a service over the lifetime of the project.  For example if I need to change the password
for the api "my_twitter_account", just increment the revision to identify to mimosa-vault that a different password
should be derived.

## Default Config

vault:
  extensionRegex: /.vault.[a-zA-Z]+$/    # regex indicating file extensions this module should process

  passwordGenerationSecret: null    # path to secret passphrase which should be used to derive the secrets
                                    # -- should refer to a file at a path outside of the project source control --
                                    # if null, mimosa will use the path
                                    # .mimosa/vault/{app}.key within the project directory where {app} is the name
                                    # of the project as given in the package.json file

  encryptionSecret: null        # Path to secret passphrase which should be used to encrypt the generated files
                                # if left null, the output files will not be encrypted.  If defined and a file does
                                # not exist at vault.encryptionSecret mimosa-vault will write a new secret to
                                # the given path

  outputFormat: "json"          # specify the output format -- either json or commonjs.
                                # if commonjs, module will export a single function which returns the vault
                                # if encryption is used the function will expect to be passed the secret needed
                                # to decrypt the vault -- the function returns decrypted vault or throws an error
                                # if the vault with the supplied password

  mimosaPasswords: {}           # passwords which should be made available to other mimosa-modules
                                # at mimosaConfig.vault.mimosaPasswords

  enforceFilePermissions: true  # will chmod vault.secret and generated files to ensure they are readable by
                                # file owner only