Node.js Client for HashiCorp Vault

Common errors

• Error: self-signed certificate in certificate chain

  cause 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

  cause 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

  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')();`).
  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

  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.
  fix Verify that your Vault server is running and accessible at the configured `endpoint` (or `VAULT_ADDR` environment variable). Check Vault's listener configuration.

Warnings

• breaking 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`.
  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).
• gotcha 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.
  Fix: Ensure `endpoint` values like `http://127.0.0.1:8200/` are provided as `http://127.0.0.1:8200`.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install node-vault npm
• yarn add node-vault yarn
• pnpm add node-vault pnpm

Imports

• vault
  wrong:

  import { vault } from 'node-vault';

  correct:

  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
  wrong:

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

  correct:

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

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

  import { ClientOptions } from 'node-vault';

  correct:

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

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

Quickstart

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();