@creditkarma/vault-client
v1.0.0
Published
A client for communicating with Hashicorp Vault written in TypeScript
Downloads
2,296
Readme
Vault Client
A client for Hashicorp Vault written in TypeScript.
Install
$ npm install --save @creditkarma/vault-client
Usage
This library exposes two classes for working with Vault, VaultClient and VaultService. VaultClient provides a slightly higher level of abstraction and a more limited API.
VaultClient
VaultClient provides two methods: get and set. Both methods return Promises.
Options
VaultClient expects the access token for Vault to be available in a local file. The path to this file is passed as an option.
Available options:
- apiVersion - API version to use. Currently this can only be 'v1'.
- protocol - The protocol to use 'http' or 'https'. Defaults to 'http'.
- destination - The location of the Vault instance. Defaults to 'localhost:8200'.
- mount - The mount at which secrets can be found. Defaults to 'secret'.
- namespace - A namespace for secrets. This path will be prepended to all get/set requests. Defaults to ''.
- tokenPath - The local file path to a file containing the Vault token. Defaults to '/tmp/token'.
- requestOptions - Options passed to the underlying Request library. The options can be overriden on a per-request basis by passing an optional final parameter to any of the service or client methods. This will be used to set up TLS.
Mount vs Namespace
The mount is the underlying Vault path at which secrets are stored. By default this is secret
. So all of your secrets would be stored at an address like: http://localhost:8200/secret/<key>
. This can be configured differently per Vault instance.
The namespace is an addition on this path to organize your secrets. Your service may share a Vault instance with other services. The namespace could then be your service name. All your secrets would be stored at: http://localhost:8200/secret/<namespace>/<key>
.
Data Formatting
When a secret is written to Vault the value you set will be wrapped in an object of this form:
{
"value": value
}
When reading values with VaultClient objects of this form are assumed. If there is no value property an exception will be raised. When performing a get only the value of the value key will be returned. This allows get and set methods to operate on primitive values.
Example
import { IHVConfig, VaultClient } from '@creditkarma/vault-client'
const options: IHVConfig = {
apiVersion: 'v1',
protocol: 'http',
destination: 'localhost:8200',
mount: 'secret',
namespace: '',
tokenPath: '/tmp/token',
requestOptions: {
headers: {
host: 'localhost'
}
}
}
const client: VaultClient = new VaultClient(options)
// Because we set a namespace this is actually written to 'secret/key'
client.set('key', 'value').then(() => {
// value successfully written
client.get<string>('key').then((val: string) => {
// val = 'value'
})
})
VaultService
VaultService provides more direct access to the raw Vault HTTP API. Method arguments and method return types conform to the HTTP Vault API.
Options
VaultService accepts a sub-set of the options that VaultClient accepts:
- apiVersion
- protocol
- destination
- requestOptions
Example
Like VaultClient all methods return Promises.
import { IServiceConfig, VaultService } from '@creditkarma/vault-client'
const options: IServiceConfig = {
apiVersion: 'v1',
protocol: 'http',
destination: 'localhost:8200',
requestOptions: {
headers: {
host: 'localhost'
}
}
}
const service: VaultService = new VaultService(options)
service.status()
service.init({ secret_shares: 1, secret_threshold: 1 })
service.unseal({ key: 'key', reset: true })
service.read(path, token)
service.write(path, value, token)
Running Tests
The good ol' npm test
will work. However, running tests requires a running Vault server. This is done with docker. If you don't have docker-compose
on your system you will be unable to run tests. Make sure you have docker.
$ npm test
You can spin up the Vault server without running tests:
$ npm run docker
This docker image has a little sugar on top of the base Vault image. It exposes an endpoint for retrieving the token.
$ curl localhost:8201/client-token
Contributing
For more information about contributing new features and bug fixes, see our Contribution Guidelines. External contributors must sign Contributor License Agreement (CLA)
License
This project is licensed under Apache License Version 2.0