node-vault

library0.12.0jsnpmunverified

node-vault is a JavaScript client library for interacting with HashiCorp's Vault HTTP API, primarily designed for Node.js environments. The current stable version is 0.12.0, requiring Node.js 18.0.0 or higher. The project demonstrates a consistent release cadence with several minor and patch releases in the past year, indicating active maintenance. It provides a comprehensive wrapper around the Vault API, simplifying operations such as secret management (read, write, update, delete, list), authentication (e.g., Kubernetes Auth, token-based), and server lifecycle management (init, unseal). A key differentiator is its direct support for TypeScript with included definitions and its focus on being a reliable, actively developed client for Node.js users needing to integrate with Vault. It also allows configuration via environment variables for common Vault settings.

auth-security http-networking

npm install node-vault

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-VAULT

node-vault

auth-securityjavascriptv0.12.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

vault

✓ import vault from 'node-vault';

✗ import { vault } from 'node-vault';

The 'node-vault' package exports a default function that acts as the client constructor. It is not a named export.

vault

✓ const vault = require('node-vault');

✗ const { vault } = require('node-vault');

In CommonJS, the package exports a default function that should be imported directly, not destructured.

ClientOptions

✓ import type { ClientOptions } from 'node-vault';

✗ import { ClientOptions } from 'node-vault';

TypeScript type for configuration options. Use 'import type' to avoid bundling types in runtime code.

This quickstart demonstrates how to initialize the node-vault client, write, read, list, update, and delete a secret using environment variables for configuration. It includes basic error handling.

import vault from 'node-vault'; async function runVaultOperations() { const vaultClient = vault({ apiVersion: 'v1', endpoint: process.env.VAULT_ADDR ?? 'http://127.0.0.1:8200', token: process.env.VAULT_TOKEN ?? '', // Recommended to use VAULT_TOKEN env var for actual usage }); if (!vaultClient.token) { console.warn("VAULT_TOKEN environment variable not set. Operations requiring authentication will likely fail."); } const secretPath = 'secret/data/my-app/config'; const dataToWrite = { value: 'super-secret-data-' + Date.now(), environment: 'development' }; try { console.log(`Writing secret to ${secretPath}...`); await vaultClient.write(secretPath, { data: dataToWrite }); console.log('Secret written successfully.'); console.log(`Reading secret from ${secretPath}...`); const result = await vaultClient.read(secretPath); console.log('Secret read:', result.data.data); console.log('Listing secrets in secret/metadata/my-app/'); const listResult = await vaultClient.list('secret/metadata/my-app/'); console.log('Listed keys:', listResult.data.keys); console.log(`Updating secret at ${secretPath}...`); await vaultClient.update(secretPath, { data: { updatedField: 'newValue' } }); console.log('Secret updated successfully.'); console.log(`Deleting secret at ${secretPath}...`); await vaultClient.delete(secretPath); console.log('Secret deleted successfully.'); } catch (error: any) { console.error('Vault operation failed:', error.message); if (error.response?.data) { console.error('Vault API Error Details:', error.response.data); } if (error.message.includes('permission denied')) { console.error('Ensure your Vault token has appropriate policies (read, write, list, delete) for secret/data/my-app/.'); } } } runVaultOperations();

Debug

Known issues

breakingVersions of `node-vault` prior to `v0.11.0` (specifically `<= v0.10.0`) are compatible with older Node.js versions (>= 6.x), but these older client versions contain multiple known security vulnerabilities. It is strongly recommended to upgrade to Node.js 18+ and `node-vault >= v0.11.0`.

fix

Upgrade your Node.js environment to version 18.0.0 or higher, then upgrade `node-vault` to `v0.11.0` or later (current stable is 0.12.0).

affects: <=0.10.0

gotchaThe `endpoint` URL option (or `VAULT_ADDR` environment variable) should not contain a trailing slash. The client automatically strips trailing slashes to prevent malformed request URIs, which can lead to unexpected 404s or incorrect path resolution if you try to manually compensate.

fix

Ensure `endpoint` values like `http://127.0.0.1:8200/` are provided as `http://127.0.0.1:8200`.

affects: >=0.1.0

gotchaThe `update` method performs an HTTP `PATCH` request with the `application/merge-patch+json` content type. This differs from a full `PUT` and applies partial updates. For KV2 secrets, this typically means merging `data` fields. Ensure your Vault policies and expectations align with a merge-patch operation.

fix

Be aware that `update` will merge fields. If a complete overwrite is needed, `vault.write()` should be used instead, though `write` can also merge depending on the Vault secret engine and path.

affects: >=0.1.0

gotchaDisabling SSL certificate verification via `VAULT_SKIP_VERIFY` environment variable or client `requestOptions` for `httpsAgent` should be avoided in production environments due to severe security implications. This can lead to man-in-the-middle attacks.

fix

Always use valid, trusted SSL certificates for your Vault server and ensure that `VAULT_SKIP_VERIFY` is not set in production. Configure your Node.js environment with appropriate CA certificates if necessary.

affects: >=0.1.0

Errors

Common errors & fixes

Error: self-signed certificate in certificate chain

Connecting to a Vault instance (often local development setups) that uses a self-signed SSL certificate without Node.js trusting it.

fix

For development, set the `VAULT_SKIP_VERIFY=true` environment variable (NOT recommended for production). For production, ensure your Vault instance uses a trusted certificate and your Node.js environment is configured to trust the issuing CA.

Vault Error: permission denied

The Vault token provided to the client lacks the necessary capabilities (policies) to perform the requested operation on the specified path.

fix

Verify the Vault token being used has the appropriate policies attached. Use `vault token capabilities <token> <path>` or check Vault audit logs to debug policy issues.

TypeError: vault.read is not a function

The `node-vault` module was imported incorrectly, typically by not calling the default exported function to instantiate a client object (e.g., `const vault = require('node-vault');` instead of `const vaultClient = require('node-vault')();`).

fix

Ensure you call the imported `node-vault` function to get a client instance: `const vaultClient = require('node-vault')({ /* options */ });` or `import createVaultClient from 'node-vault'; const vaultClient = createVaultClient({ /* options */ });`

Error: connect ECONNREFUSED 127.0.0.1:8200

The `node-vault` client could not connect to the specified Vault server endpoint. This often means Vault is not running or is listening on a different address/port.

fix

Verify that your Vault server is running and accessible at the configured `endpoint` (or `VAULT_ADDR` environment variable). Check Vault's listener configuration.

Upgrade

Version history

0.12.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

7 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/nodevault/node-vault ↗

packagehttps://www.npmjs.com/package/node-vault ↗