vvauth

2.0.2 verified Sat Apr 25 auth: no javascript

Vault Auth helper for authenticating to HashiCorp Vault using JWT or SSH agent methods. Version 2.0.2 provides token retrieval and environment variable management via a YAML config file (.vauthrc) with macro expansion for profiles, environment variables, and remote secrets. Differentiators include SSH agent login, dynamic secret resolution, and multi-profile support. Release cadence is irregular; primarily maintained by a single developer.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module not supported ↓

cause Using CommonJS require() to load vvauth, which is ESM-only.

fix

Change to import statement: import vvauth from 'vvauth'; and ensure your package is type: module.

error Error: VAULT_TOKEN not found in response ↓

cause JWT or SSH login request succeeded but Vault did not return a token, possibly due to misconfigured role or auth backend.

fix

Check Vault auth mount path and role configuration. Ensure the JWT token or SSH certificate are valid.

error Error: Cannot find module 'node-vault' ↓

cause Missing peer dependency node-vault, which is required by vvauth.

fix

Install node-vault: npm install node-vault

error Error: ENOENT: no such file or directory, open '.vauthrc' ↓

cause vvauth cannot find a configuration file. It looks for .vauthrc in current directory or home.

fix

Create a .vauthrc file with required vault_addr and auth method settings, or set the VAUTHRC environment variable to point to your config file.

Warnings

gotcha ESM-only package. Requiring via require('vvauth') will throw ERR_REQUIRE_ESM. ↓

fix Convert to ES module (type: module in package.json) or use dynamic import: const vvauth = await import('vvauth').

gotcha .vauthrc file must be YAML, not JSON. Parsing a JSON file may silently fail. ↓

fix Use YAML format for configuration file.

gotcha Macro expansion in .vauthrc uses string replacement; escaping special characters in values can break expansion. ↓

fix Avoid using ${} or $$ in values; use raw strings or escape them properly.

Install

npm install vvauth

yarn add vvauth

pnpm add vvauth

Imports

default
wrong
```
const vvauth = require('vvauth')
```
correct
```
import vvauth from 'vvauth'
```
vvauth is ESM-only; CommonJS require will fail.

loginJWT

wrong

const { loginJWT } = require('vvauth')

correct

import { loginJWT } from 'vvauth'

Named export for JWT authentication. Requires ESM.

loginSSH

wrong

import loginSSH from 'vvauth'

correct

import { loginSSH } from 'vvauth'

loginSSH is a named export, not default.

Quickstart

Demonstrates JWT and SSH agent authentication, returning VAULT_TOKEN. Reads config from .vauthrc file or environment.

import { loginJWT, loginSSH } from 'vvauth';
import { promises as fs } from 'fs';

async function main() {
  // JWT login: provide role and JWT token
  const vaultToken = await loginJWT('my-jwt-role', 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...');
  console.log('VAULT_TOKEN:', vaultToken);

  // SSH login: uses SSH agent, role from env or config
  try {
    const sshToken = await loginSSH();
    console.log('SSH login token:', sshToken);
  } catch (err) {
    console.error('SSH login failed:', err.message);
  }
}

main().catch(console.error);