Node.js HashiCorp Vault Client

Common errors

• Error: Unauthorized (or similar authentication failure messages)

  cause In versions prior to 0.6.1, the Vault token might not have been correctly included in request headers.
  fix Upgrade `node-vault-client` to version `0.6.1` or later. Also, double-check your authentication configuration (e.g., AppRole `role_id` and `secret_id`, or token validity).

• Error: Client with name 'my-client' already booted.

  cause You are calling `VaultClient.boot()` with the same name multiple times without clearing it in older versions, or a previous instance was not properly managed.
  fix Upgrade to `node-vault-client@1.0.1` or newer. If upgrading isn't an option, ensure `VaultClient.boot()` is called only once for a given name, or use `VaultClient.get()` to retrieve an existing instance.

• Error: Cannot find module 'config'

  cause The `config` package is a peer dependency and was not installed in your project.
  fix Install the `config` package: `npm install config` or `yarn add config`.

• SyntaxError: Cannot use import statement outside a module

  cause You are attempting to use ES module `import` syntax in a Node.js environment configured for CommonJS, or the `node-vault-client` package is being treated as CommonJS.
  fix Change your import statement to use CommonJS `require()`: `const VaultClient = require('node-vault-client');`. If you must use ESM, consider a transpiler or a dynamic `import()` call if `node-vault-client` doesn't provide ESM entry points.

Warnings

• breaking Versions prior to `0.6.1` had a critical bug where the Vault token was not correctly passed in request headers, leading to authentication failures or unauthorized access attempts.
  Fix: Upgrade to `node-vault-client@0.6.1` or any subsequent version to ensure proper token handling.
• gotcha Attempting to call `VaultClient.boot()` multiple times with the same instance `name` in versions prior to `1.0.1` could lead to unexpected behavior or errors related to client re-initialization.
  Fix: Upgrade to `node-vault-client@1.0.1` or newer, which addresses this issue. Alternatively, ensure `VaultClient.boot()` is called only once per unique client name in older versions.
• gotcha The package lists `config` as a peer dependency with a wide range (`>=1 <4`). While flexible, this means the `config` package must be manually installed by the user, and major version changes within that range could introduce subtle incompatibilities if not tested.
  Fix: Explicitly install the `config` package (`npm install config` or `yarn add config`) in your project. It is recommended to pin a specific major version of `config` if stability is critical.
• gotcha This library requires Node.js version 14 or higher. Running it on older Node.js environments will result in runtime errors due to unsupported syntax or APIs.
  Fix: Ensure your project's Node.js runtime is version 14.0.0 or newer. Update your Node.js installation if necessary.

Install

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

Imports

• VaultClient
  wrong:

  import VaultClient from 'node-vault-client';

  correct:

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

  This library is primarily distributed as a CommonJS module. Use `require()` for standard Node.js environments. Direct `import` syntax will typically fail in ESM projects without specific configuration.
• VaultClient.boot
  wrong:

  import { boot } from 'node-vault-client';

  correct:

  const VaultClient = require('node-vault-client');
  const vaultClientInstance = VaultClient.boot('main', { /* ...options */ });

  The `boot` method is a static function accessed via the `VaultClient` object, not a top-level named export. It's the primary way to initialize and retrieve a client instance.
• VaultClient (TypeScript)
  wrong:

  import type { VaultClient } from 'node-vault-client';

  correct:

  // Install @types/node-vault-client if available, or rely on inferred types.

  As a pure JavaScript library, explicit TypeScript type exports are not directly provided by the package itself. Users relying on TypeScript might need `@types/node-vault-client` or leverage TypeScript's inference capabilities.

Quickstart

This quickstart demonstrates how to initialize the Vault client using AppRole authentication, read a secret, and write data to Vault. It uses environment variables for sensitive credentials.

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

// Initialize the Vault client. The 'boot' method handles singleton instance management.
// Ensure VAULT_APP_ROLE_ID and VAULT_APP_ROLE_SECRET_ID environment variables are set.
const vaultClient = VaultClient.boot('main', {
    api: { url: 'https://vault.example.com:8200/' }, // Replace with your Vault server URL
    auth: {
        type: 'appRole', // Supports 'appRole', 'token', 'iam', 'kubernetes'
        config: {
            role_id: process.env.VAULT_APP_ROLE_ID ?? 'your-approle-role-id',
            secret_id: process.env.VAULT_APP_ROLE_SECRET_ID ?? 'your-approle-secret-id' // Required for AppRole
        }
    },
    // Optional: Pass 'false' to disable logging, or a custom logger object.
    logger: console
});

// Read a secret from a specified path in Vault
vaultClient.read('secret/data/my-application/config')
    .then(response => {
        console.log('Successfully read secret:', response.data.data); // Vault K/V v2 stores data in .data.data
    })
    .catch(e => {
        console.error('Error reading secret:', e.message);
        // Implement robust error handling, e.g., retry logic, specific Vault error codes.
    });

// Example of writing a secret to Vault
vaultClient.write('secret/data/my-application/settings', { value: 'some_setting', enabled: true })
    .then(() => console.log('Successfully wrote secret.'))
    .catch(e => console.error('Error writing secret:', e.message));