fastify-secrets-hashicorp

Fastify Secrets HashiCorp

Fastify secrets plugin for HashiCorp Vault. The plugin supports both KV Secrets Engine - Version 2 (default) and KV Secrets Engine - Version 1 (need to enable via useKVv1 flag).

Installation

npm install --save fastify-secrets-hashicorp

Usage

const Fastify = require('fastify')
const FastifySecretsHashiCorp = require('fastify-secrets-hashicorp')

const fastify = Fastify()

// Add plugin to your fastify instance
fastify.register(FastifySecretsHashiCorp, {
  secrets: {
    dbPassword: {
      name: 'secret-name',
      key: 'value'
    }
  },
  clientOptions: {
    vaultOptions: {
      token: 'example-token',
      endpoint: 'http://127.0.0.1:8200'
    },
    mountPoint: 'example-mount'
  }
})

// Access your secrets
fastify.ready().then(() => {
  console.log(fastify.secrets.dbPassword) // content of 'example-mount/secret-name'
})

Plugin options

Assuming a secret has been written using the vault CLI like this:

VAULT_ADDR='http://127.0.0.1:8200' vault write myproject/database password=mysecret

The plugin can be initialised to read this secret as follows:

fastify.register(FastifySecretsHashiCorp, {
  secrets: {
    dbPassword: {
      name: 'database',
      key: 'password'
    }
  },
  clientOptions: {
    vaultOptions: {
      token: '<TOKEN>',
      endpoint: 'http://127.0.0.1:8200'
    },
    mountPoint: 'myproject'
  }
})

clientOptions.mountPoint

The path to the secrets engine. Defaults to 'secret'.

clientOptions.useKVv1

If this flag is set to true, will read from the Vault using KV Secrets Engine - Version 1. Defaults to false. How to use the plugin with kv-v1:

fastify.register(FastifySecretsHashiCorp, {
  secrets: {
    dbPassword: {
      name: 'database',
      key: 'password'
    }
  },
  clientOptions: {
    vaultOptions: {
      token: '<TOKEN>',
      endpoint: 'http://127.0.0.1:8200'
    },
    mountPoint: 'myproject',
    useKVv1: true
  }
})

clientOptions.vaultOptions

Initialisation options that are sent to node-vault, typed as VaultOptions.

The most important being:

• vaultOptions.token: Vault access token. Defaults to process.env.VAULT_TOKEN.
• vaultOptions.endpoint: Endpoint to the Vault API. Defaults to process.env.VAULT_ADDR else 'http://127.0.0.1:8200'

Assumptions

• A vault server is running and has been unsealed
• A secrets engine is available at secrets/ (or at the provided mountPoint in options) and us using either KV Secrets Engine - Version 2 or KV Secrets Engine - Version 1 (with useKVv1 option set to true)
• clientOptions.vaultOptions.token is provided as an option, or VAULT_TOKEN is available as an environment variable
• clientOptions.vaultOptions.endpoint is provided as an option, or VAULT_ADDR is available as an environment variable

Secrets Engine

We assume that the kv-v2 secrets engine is being used. If vault is started in dev mode (vault server -dev) it defaults to the kv-v2 engine, mounted at secrets/. In order to use the dev server, with kv-v1, you need to remove it and mount a kv-v1 secrets provider instead:

VAULT_ADDR='http://127.0.0.1:8200' vault secrets disable secret
VAULT_ADDR='http://127.0.0.1:8200' vault secrets enable -version=1 -path=secret kv

Or alternatively, mount kvv1 on a different path, without removing the kv-v2 engine.

VAULT_ADDR='http://127.0.0.1:8200' vault secrets enable -version=1 -path=kvv1 kv

Contributing

See CONTRIBUTING.md

License

Copyright NearForm Ltd 2021. Licensed under the Apache-2.0 license.