{"id":12746,"library":"node-vault","title":"Node.js Client for HashiCorp Vault","description":"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.","status":"active","version":"0.12.0","language":"javascript","source_language":"en","source_url":"git://github.com/nodevault/node-vault","tags":["javascript","vault","hashicorp","secrets","manage","client"],"install":[{"cmd":"npm install node-vault","lang":"bash","label":"npm"},{"cmd":"yarn add node-vault","lang":"bash","label":"yarn"},{"cmd":"pnpm add node-vault","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The 'node-vault' package exports a default function that acts as the client constructor. It is not a named export.","wrong":"import { vault } from 'node-vault';","symbol":"vault","correct":"import vault from 'node-vault';"},{"note":"In CommonJS, the package exports a default function that should be imported directly, not destructured.","wrong":"const { vault } = require('node-vault');","symbol":"vault","correct":"const vault = require('node-vault');"},{"note":"TypeScript type for configuration options. Use 'import type' to avoid bundling types in runtime code.","wrong":"import { ClientOptions } from 'node-vault';","symbol":"ClientOptions","correct":"import type { ClientOptions } from 'node-vault';"}],"quickstart":{"code":"import vault from 'node-vault';\n\nasync function runVaultOperations() {\n  const vaultClient = vault({\n    apiVersion: 'v1',\n    endpoint: process.env.VAULT_ADDR ?? 'http://127.0.0.1:8200',\n    token: process.env.VAULT_TOKEN ?? '', // Recommended to use VAULT_TOKEN env var for actual usage\n  });\n\n  if (!vaultClient.token) {\n    console.warn(\"VAULT_TOKEN environment variable not set. Operations requiring authentication will likely fail.\");\n  }\n\n  const secretPath = 'secret/data/my-app/config';\n  const dataToWrite = {\n    value: 'super-secret-data-' + Date.now(),\n    environment: 'development'\n  };\n\n  try {\n    console.log(`Writing secret to ${secretPath}...`);\n    await vaultClient.write(secretPath, { data: dataToWrite });\n    console.log('Secret written successfully.');\n\n    console.log(`Reading secret from ${secretPath}...`);\n    const result = await vaultClient.read(secretPath);\n    console.log('Secret read:', result.data.data);\n\n    console.log('Listing secrets in secret/metadata/my-app/');\n    const listResult = await vaultClient.list('secret/metadata/my-app/');\n    console.log('Listed keys:', listResult.data.keys);\n\n    console.log(`Updating secret at ${secretPath}...`);\n    await vaultClient.update(secretPath, { data: { updatedField: 'newValue' } });\n    console.log('Secret updated successfully.');\n\n    console.log(`Deleting secret at ${secretPath}...`);\n    await vaultClient.delete(secretPath);\n    console.log('Secret deleted successfully.');\n\n  } catch (error: any) {\n    console.error('Vault operation failed:', error.message);\n    if (error.response?.data) {\n      console.error('Vault API Error Details:', error.response.data);\n    }\n    if (error.message.includes('permission denied')) {\n        console.error('Ensure your Vault token has appropriate policies (read, write, list, delete) for secret/data/my-app/.');\n    }\n  }\n}\n\nrunVaultOperations();","lang":"typescript","description":"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."},"warnings":[{"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).","message":"Versions 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`.","severity":"breaking","affected_versions":"<=0.10.0"},{"fix":"Ensure `endpoint` values like `http://127.0.0.1:8200/` are provided as `http://127.0.0.1:8200`.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"Disabling 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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"Connecting to a Vault instance (often local development setups) that uses a self-signed SSL certificate without Node.js trusting it.","error":"Error: self-signed certificate in certificate chain"},{"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.","cause":"The Vault token provided to the client lacks the necessary capabilities (policies) to perform the requested operation on the specified path.","error":"Vault Error: permission denied"},{"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 */ });`","cause":"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')();`).","error":"TypeError: vault.read is not a function"},{"fix":"Verify that your Vault server is running and accessible at the configured `endpoint` (or `VAULT_ADDR` environment variable). Check Vault's listener configuration.","cause":"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.","error":"Error: connect ECONNREFUSED 127.0.0.1:8200"}],"ecosystem":"npm"}