node-vault-client

v2.1.2

Published

6 days ago

A Vault Client implemented in pure javascript for HashiCorp Vault. It supports variety of Auth Backends and performs lease renewal for issued auth token.

0High
0Medium
0Low

Node.js Vault Client

A Vault Client implemented in pure javascript for HashiCorp Vault. It supports variety of Auth Backends and performs lease renewal for issued auth token.

Install

npm install --save node-vault-client

Requirements

Node.js >= 18 — the client uses the native fetch API.

Example

const VaultClient = require('node-vault-client');

const vaultClient = VaultClient.boot('main', {
    api: { url: 'https://vault.example.com:8200/' },
    auth: { 
        type: 'appRole', // one of: 'appRole' | 'token' | 'iam' | 'kubernetes'
        config: { role_id: '637c065f-c644-5e12-d3d1-e9fa4363af61' } 
    },
});

vaultClient.read('secret/tst').then(lease => {
    console.log(lease.getData()); // read() resolves to a Lease; use getData()/getValue(key)
}).catch(e => console.error(e));

Supported Auth Backends

AWS IAM auth

const vaultClient = VaultClient.boot('main', {
    api: {
        url: 'https://vault.example.com:8200/',
        namespace: 'some_namespace',                   // Optional. X-Vault-Namespace header (canonical location; auth.config.namespace is honored as a legacy fallback)
    },
    auth: {
        type: 'iam',
        mount: 'aws',                                  // Optional. Vault AWS auth mount point ("aws" by default)
        config: {
            role: 'my_iam_role',
            iam_server_id_header_value: 'https://vault.example.com:8200/', // Optional. X-Vault-AWS-IAM-Server-ID header
            region: 'eu-central-1',                     // Optional. AWS STS region (see below)
            credentials: {                             // Optional. Resolved from the AWS provider chain when omitted
                accessKeyId: process.env.AWS_ACCESS_KEY_ID,
                secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
            },
        },
    },
});

`region`

By default the signed GetCallerIdentity request targets the global STS endpoint sts.amazonaws.com and the SigV4 credential scope is bound to us-east-1. Set config.region to sign against a regional STS endpoint instead — the request is then sent to sts.<region>.amazonaws.com and the signature scope is bound to that region. This is required when Vault's sts_region / sts_endpoint is configured for a non-us-east-1 region (e.g. eu-central-1); otherwise STS rejects the replayed request with SignatureDoesNotMatch — Credential should be scoped to a valid region. Omitting region preserves the previous (global-endpoint) behavior.

AppRole auth

const vaultClient = VaultClient.boot('main', {
    api: { url: 'https://vault.example.com:8200/' },
    auth: {
        type: 'appRole',
        mount: 'approle',                              // Optional. Vault AppRole auth mount point ("approle" by default)
        config: {
            role_id: '637c065f-c644-5e12-d3d1-e9fa4363af61', // Required. RoleID of the AppRole
            secret_id: '...',                          // Optional. Required when bind_secret_id is enabled
        },
    },
});

Token auth

const vaultClient = VaultClient.boot('main', {
    api: { url: 'https://vault.example.com:8200/' },
    auth: {
        type: 'token',
        mount: 'token',                                // Optional. Vault token auth mount point ("token" by default)
        config: {
            token: 's.xxxxxxxxxxxxxxxxxxxxxxxx',       // Required. Vault token
        },
    },
});

Kubernetes auth

const vaultClient = VaultClient.boot('main', {
    api: { url: 'https://vault.example.com:8200/' },
    auth: {
        type: 'kubernetes',
        mount: 'kubernetes',                           // Optional. Vault Kubernetes auth mount point ("kubernetes" by default)
        config: {
            role: 'my_k8s_role',                       // Required. Role configured in the Vault Kubernetes auth backend
            tokenPath: '/var/run/secrets/kubernetes.io/serviceaccount/token', // Optional. Defaults to the in-pod service-account token path
        },
    },
});

API

VaultClient

VaultClient
- new VaultClient(options)
- instance
  - .fillNodeConfig()
  - .read(path) ⇒ Promise.<Lease>
  - .list(path) ⇒ Promise.<Lease>
  - .write(path, data) ⇒ Promise.<Object>
  - .delete(path) ⇒ Promise.<Object>
  - .update(path, data) ⇒ Promise.<Object>
  - .request(method, path, [data]) ⇒ Promise.<Object>
  - .deleteVersions(path, versions) ⇒ Promise.<Object>
  - .undeleteVersions(path, versions) ⇒ Promise.<Object>
  - .destroyVersions(path, versions) ⇒ Promise.<Object>
  - .readMetadata(path) ⇒ Promise.<Object>
  - .deleteMetadata(path) ⇒ Promise.<Object>
  - .close()
- static
  - .boot(name, [options]) ⇒ VaultClient
  - .get(name) ⇒ VaultClient
  - .clear([name])
Lease

Return contract: read() and list() resolve to a Lease — use its accessors to extract the secret data. Every other data-plane method (write, delete, update, request and the KV v2 helpers) resolves to the raw parsed Vault response body, which may be empty/undefined for 204 No Content responses.

new VaultClient(options)

Client constructor function.

| Param | Type | Default | Description | | --- | --- | --- | --- | | options | Object | | | | options.api | Object | | | | options.api.url | String | | the url of the vault server | | [options.api.apiVersion] | String | v1 | | | [options.api.requestOptions] | Object | | extra options merged into every HTTP request (see Custom transport) | | [options.api.namespace] | String | | Optional. Vault namespace, sent as the X-Vault-Namespace header on every request — login, token lookup/renewal, and all secret operations — for every auth type. This is the canonical location; auth.config.namespace is still honored for backward compatibility. | | [options.api.kv.autoDetect] | boolean | false | auto-detect the KV version of each mount on first use (see KV v2 & generic backends) | | [options.api.engines] | Object | {} | static mount-to-version map, e.g. { secret: 2, legacy: 1 } (see KV v2 & generic backends) | | options.auth | Object | | | | options.auth.type | String | | | | [options.auth.mount] | String | | Vault auth backend mount point; default varies per method (e.g. "aws" for iam, "approle", "token", "kubernetes") | | options.auth.config | Object | | auth configuration variables | | [options.auth.config.namespace] | String | | Optional. Legacy location for the Vault namespace (see api.namespace). Sent as the X-Vault-Namespace header on every request for every auth type. | | [options.logger] | Object | false | | Logger that supports "error", "info", "warn", "trace", "debug" methods. Uses console by default. Pass false to disable logging. |

Custom transport (proxy / self-signed TLS)

options.api.requestOptions is shallow-merged into every underlying fetch() call, so you can route traffic through a proxy/SOCKS agent or trust a self-signed / internal-CA Vault. Pass an undici dispatcher (request semantics like method and body always win; headers are merged with per-request headers taking precedence):

const { Agent, ProxyAgent } = require('undici');

// Trust an internal/self-signed CA (preferred over disabling verification)
const vaultClient = VaultClient.boot('main', {
    api: {
        url: 'https://vault.internal:8200/',
        requestOptions: {
            dispatcher: new Agent({ connect: { ca: require('fs').readFileSync('/etc/ssl/internal-ca.pem') } }),
        },
    },
    auth: { type: 'token', config: { token: '...' } },
});

// Route through an HTTP proxy / SOCKS agent
const proxied = VaultClient.boot('proxied', {
    api: { url: 'https://vault.example.com:8200/', requestOptions: { dispatcher: new ProxyAgent('http://proxy:8080') } },
    auth: { type: 'token', config: { token: '...' } },
});

For the self-signed-CA case you can also use the process-wide NODE_EXTRA_CA_CERTS=/path/ca.pem env var with no code change. Only disable verification (new Agent({ connect: { rejectUnauthorized: false } })) in throwaway/dev setups — it removes MITM protection.