vault-client

A node client for HashiCorp's vault. In addition to supporting basic http interaction with a vault api, it will also manage:

• authentication & reauthentication based on token lease_duration
• including the current access token on every request as the X-Vault-Token header
• caching & renewing secrets based on lease_duration
• notifying subscribers of secret renewals

Installing

npm install --save vault-client

Getting Started

const Vault = require('vault-client');
const client = new Vault({
    url: 'https://vault.example.com'
});

async.series([
    // first, we need to authenticate with vault
    function login(next) {
        vault.login({
            backend: 'userpass',
            options: {
                username: 'bob',
                password: 'password1'
            }
        }, next);
    },

    // let's add some secrets
    function addSecrets(next) {
        const secrets = [{
            path: '/secret/foo',
            data: {
                foo: 'bar'
            }
        },{
            path: '/secret/bar',
            data: {
                bar: 'baz'
            }
        }];
        async.each(secrets, function(secret, done) {
            vault.post(secret.path, secret.data, done);
        }, next);
    },

    // next, we can fetch a single secret from vault
    function get(next) {
        vault.get('/secret/foo', function(err, data) {
            console.log(data);
            // {
            //   "data": {
            //     "foo": "bar"
            //   },
            //   "lease_duration": 2592000,
            //   "renewable": false
            // }
            next(err);
        });
    },

    // or, we can choose to watch a single secret. the vault client
    // will cache the fetched secret locally, and will handle renewing
    // the secret if a lease_duration is included in the response metadata
    function(next) {
        vault.watch({
            address: 'foo', // store the secret in the cache at path "foo"
            path: '/secret/foo'
        }, function(err, data) {
            const foo = vault.secret('foo');
            console.log(JSON.stringify(foo));
            // { "foo": "bar" }
            next(err, data);
        });

        // we can listen for secret renewals at the "foo" address by attaching
        // a listener to the "secret:<address>" event
        vault.on('secret:foo', function(data) {
            console.log(JSON.stringify(data))
            // { "foo": "goo" }
        });
    },

    // we can also choose to watch multiple secrets. again, the vault client
    // will handle renewing each secret based on its lease_duration.
    function(next) {
        vault.watch([{
            address: '.', // the root address, secret will be merged into the root
            path: '/secret/foo'
        }, {
            address: 'bar',
            path: '/secret/bar'
        }], function(err, data) {
            console.log(JSON.stringify(vault.secret()))
            // { "bar": { "bar": "baz" }, "foo": "bar" }
        });
    }
]);

API

Vault(options)

Creates a new vault client.

Params

| param | type | description | | :--- | :---: | :--- | | options* | {Object} | options | | options.url* | {String} | the base url of the vault server | | options.retry | {Object} | global retry settings for failed network requests. see node-retry for more info

Example

const Vault = require('vault-client');
const vault = new Vault({
    url: 'https://localhost:8200/v1'
});

vault.secret([address])

Fetch a copy of a partial branch of secret cache. If no address is specified, a copy of the entire cache will be returned.

Params

| param | type | description | | :--- | :---: | :--- | | address | {String} | an path of the cache to retrieve |

Example

const secrets = vault.secret();
console.log(JSON.stringify(secrets));
// returns a copy of the internal store
// {
//      "foo": "bar",
//      "bar": { "bar": "baz" },
//      "super": { "nested": { "secret": "s3cr3t" }}
// }

const nested = vault.secret('some.nested.secret');
console.log(nested)
// returns a copy of a branch of the store
// "s3cr3t"

vault.watch(secrets, [options], [cb])

Fetches one or more secrets from vault and caches them internally. If a secret includes a lease_duration greater than 0, this method will handle renewing them periodically. Failed attempts will be automatically retried using node-retry |

Params

| param | type | description | | :--- | :---: | :--- | | secrets* | {Object,Object[]} | | | secrets.$.address* | {String} | the caching address to use for the fetched secret's data | | secrets.$.path* | {String} | the relative url of the secret in vault | | options | {Object} | | | options.retry | {Object} | optional node-retry settings for retrying failed attempts | | cb | {Function} | node style callback |

Example

const secrets = [
    { address: '.', path: '/secret/foo' },
    { address: 'bar', path: '/secret/bar' },
    { address: 'super', path: '/secret/super' }
];

vault.watch(secrets, function(err, data) {
    // do something once all secrets have been successfully retrieved.
});

vault.on('secret:foo', function(secret) {
    // execute when secret is first retrieved and every time secret is renewed
});

vault.delete(url, [config], [cb])

Issues a DELETE request to vault. If the client is authenticated, the request will include the current client_token via the X-VAULT-TOKEN header.

Params

| param | type | description | | :--- | :---: | :--- | | url* | {String} | relative url | | config | {Object} | axios configuration object | | cb | {Function} | node style callback |

vault.head(url, [config], [cb])

Issues a HEAD request to vault. If the client is authenticated, the request will include the current client_token via the X-VAULT-TOKEN header.

Params

| param | type | description | | :--- | :---: | :--- | | url* | {String} | relative url | | config | {Object} | axios configuration object | | cb | {Function} | node style callback |

vault.get(url, [config], [cb])

Issues a GET request to vault. If the client is authenticated, the request will include the current client_token via the X-VAULT-TOKEN header.

Params

| param | type | description | | :--- | :---: | :--- | | url* | {String} | relative url | | config | {Object} | axios configuration object | | cb | {Function} | node style callback |

Example

// node style
vault.get('/secrets/foo', {
    timeout: 1000
}, function(err, results) {
    console.log(results);
})

// promise style
vault.get('/secrets/foo', {
    timeout: 1000
}).then(function(res) {
    // res is an axios res object
}).catch(function(err) {
    // catch any errors
});

vault.login(options, [callback])

Create a new session with vault server and periodically refresh it.
currently the 'userpass' backend is the only supported backend

Params

| param | type | description | | :--- | :---: | :--- | | options* | {Object} | login options | | options.backend* | {String}| the backend to use. currently supported backends: userpass | | options.options* |{Object}| backend specific options | | options.retry |{Object}` | in the event of network errors, the client will continue attempting the login using node-retry |

vault.patch(url, [data], [config], [cb])

Issues a PATCH request to vault. If the client is authenticated, the request will include the current client_token via the X-VAULT-TOKEN header.

Params

| param | type | description | | :--- | :---: | :--- | | url* | {String} | relative url | | data | {Object} | request data | | config | {Object} | axios configuration object | | cb | {Function} | node style callback |

vault.post(url, [data], [config], [cb])

Issues a POST request to vault. If the client is authenticated, the request will include the current client_token via the X-VAULT-TOKEN header.

Params

| param | type | description | | :--- | :---: | :--- | | url* | {String} | relative url | | data | {Object} | request data | | config | {Object} | axios configuration object | | cb | {Function} | node style callback |

vault.put(url, [data], [config], [cb])

Issues a PUT request to vault. If the client is authenticated, the request will include the current client_token via the X-VAULT-TOKEN header.

Params

| param | type | description | | :--- | :---: | :--- | | url* | {String} | relative url | | data | {Object} | request data | | config | {Object} | axios configuration object | | cb | {Function} | node style callback |

Events

| name | callback | description | | :--- | :--- | :--- | | error | function(err) | all errors will bubble to here | | error:login | function(err) | login errors |

Auth Backends

Following are backend specific login options

userpass

{
    backend: 'userpass',
    options: {
        username: '<vault-userpass-username>',
        password: '<vault-userpass-password>'
    }
}

Todo

• [ ] add support for additional auth backends

Testing

run the test suite (requires docker-compose v1.7+)

docker-compose up

run coverage

docker-compose run client npm run coverage

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

License

Copyright (c) 2016 Chris Ludden Licensed under the MIT License;