Hashi Vault JS

!GitHub issues
!GitHub code size in bytes
!GitHub repo file count
!GitHub top language
!GitHub contributors
!GitHub package.json dependency version (prod)
!npm
!NPM

This ES6 module provides a set of functions to help JavaScript Developers working with HashiCorp Vault to authenticate and access API endpoints using JavaScript _promises_.

This package is NOT affected by the _log4shell_ CVE-2021-44228 vulnerability!

Requirements (MacOS/Windows)

* NodeJs
* Minimum: v20.x
* Recommended: v22.x
* npm
* Tested on: v10.8.x
* HashiCorp Vault
* Minimum: v1.16.x
* Accepted: v1.17.x
* Recommended: v1.18.x

Note: Depending on your Windows setup windows-build-tools may need to be installed first. Also, for MacOS users, you should have xcode-select or entire Xcode App installed.

Table of Contents

* Install
* Uninstall
* Release notes and versions
* Class Constructor
* Module usage
* TypeScript
* Mount points
* Error handling
* Available functions
* Coverage and limitations
* Test environment
* References
* Contributing
* Reporting an issue
* Suggesting a new feature
* Authors
* Contributors
* License

$3

``bash
npm install hashi-vault-js --save
`

For TypeScript projects, type definitions are included automatically. No need for @types/hashi-vault-js.

$3

`bash
npm uninstall hashi-vault-js
`

$3

Change log

$3

`javascript
{
// Indicates if the HTTP request to the Vault server should use
// HTTPS (secure) or HTTP (non-secure) protocol
https: true,
// If https is true, then provide client certificate, client key and
// the root CA cert
// Client cert and key are optional now
cert: './client.crt',
key: './client.key',
cacert: './ca.crt',
// Indicate the server name/IP, port and API version for the Vault,
// all paths are relative to this one
baseUrl: 'https://127.0.0.1:8200/v1',
// Sets the root path after the base URL, it translates to a
// partition inside the Vault where the secret engine / auth method was enabled
// Can be passed individually on each function through mount parameter
rootPath: 'secret',
// HTTP request timeout in milliseconds
timeout: 1000,
// If should use a proxy or not by the HTTP request
// Example:
// proxy: { host: proxy.ip, port: proxy.port }
proxy: false,
// Namespace (multi-tenancy) feature available on all Vault Enterprise versions
namespace: 'admin'
}
`

$3

Note: This package covers some auth methods and secret engines. Check Limitations section for more details.

* Production

`javascript
import Vault from 'hashi-vault-js';

const vault = new Vault( {
https: true,
cert: './client.crt',
key: './client.key',
cacert: './ca.crt',
baseUrl: 'https://127.0.0.1:8200/v1',
rootPath: 'secret',
timeout: 2000,
proxy: false,
// Only for Vault Enterprise
namespace: 'ns1'
});
`

* Development

`javascript
import Vault from 'hashi-vault-js';

const vault = new Vault( {
https: true,
baseUrl: 'https://127.0.0.1:8200/v1',
rootPath: 'secret',
timeout: 5000,
proxy: false
});
`

Check health status of the Vault server:

`javascript
const status = await vault.healthCheck();
`

Perform a login on the Vault with role-id/secret-id pair, (AppRole login) and get a valid client token:

`javascript
const token = await vault.loginWithAppRole(RoleId, SecretId).client_token;
`

Perform a login on the Vault with LDAP username/password pair, and get a valid client token:

`javascript
const token = await vault.loginWithLdap(Username, Password).client_token;
`

Perform a login on the Vault with Userpass username/password pair, and get a valid client token:

`javascript
const token = await vault.loginWithUserpass(Username, Password).client_token;
`

Perform a login on the Vault with Kubernetes service accounts token, and get a valid client token:

`javascript
const token = await vault.loginWithK8s(Role, Token).client_token;
`

Perform a login on the Vault with TLS certificate and key, and get a valid client token:

`javascript
const token = await vault.loginWithCert(certName, Token).client_token;
`

Define a function to return secret engine information from the Vault:

`javascript
const secretEngineInfo = function(token) {
vault.readKVEngineConfig(token).then(function(result){
return result;
}).catch(function(error){
return error;
});
};
`

Create a new secret in the Vault:

`javascript
const Item={
name: "slack",
data: {
bot_token1: "xoxb-123456789012-1234567890123-1w1lln0tt3llmys3cr3tatm3",
bot_token2: "xoxb-123456789013-1234567890124-1w1lln0tt3llmys3cr3tatm3"
}
};

const data = await vault.createKVSecret(token, Item.name , Item.data);
`

Read a secret from the Vault:

`javascript
const secrets = await vault.readKVSecret(token, Item.name);
`

Update secret version 1 in the Vault:

`javascript
const data = await vault.updateKVSecret(token, Item.name , newData, 1);
`

$3

hashi-vault-js includes full TypeScript support with type definitions automatically generated from the source code.

Type Definitions:

* dist/index.d.ts - Main entry point with both Vault and Config exports
* dist/Vault.d.ts - Vault class with all method signatures
* dist/Config.d.ts - Configuration object types
* Declaration maps included for IDE navigation to source

Import Options:

`typescript
// Default import (recommended)
import Vault from 'hashi-vault-js';

// Named imports
import { Vault, config } from 'hashi-vault-js';

// Import config separately
import { config } from 'hashi-vault-js/config';

// Type-only import
import type { VaultClient } from 'hashi-vault-js';
`

Usage Example:

`typescript
import Vault from 'hashi-vault-js';
import { config } from 'hashi-vault-js';

// Constructor params are fully typed
const vault = new Vault({
https: true,
baseUrl: 'https://vault.example.com:8200/v1',
timeout: 5000,
namespace: 'my-namespace'
});

// Access configuration constants
console.log('Default timeout:', config.timeout);
console.log('App name:', config.appName);

async function example() {
const token = 'hvs.xxxxx';

// All method parameters and return types are inferred
const secret = await vault.readKVSecret(
token, // string
'my-secret', // string
1, // version (optional)
'secret' // mount path (optional)
);

// TypeScript knows the structure
console.log(secret.data);
}
`

TypeScript Project Configuration:

For best compatibility, use these settings in your tsconfig.json:

`json
{
"compilerOptions": {
"module": "NodeNext",
"moduleResolution": "NodeNext",
"target": "ES2020",
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"strict": true,
"skipLibCheck": true
}
}
`

$3

Most of the Vault Server API endpoints can be mounted on non-default path. For that reason, there's a last parameter in the related functions to allow using a custom mount path.

For instance, if you want to enable KV v2 on a different path, you can do so:

`shell
vault secrets enable -path=knight kv-v2
`

Now you call this helper library functions with the correct mount path:

`javascript
const config = await vault.readKVEngineConfig(token, "knight")
`

$3

This package extends the error stack to differentiate if the exception occurred on the Vault API layer or not. Also, adds a help message from the Vault API docs.

`javascript
try {
vault.function(...);
}
// An exception happened and it was thrown
catch(err) {
if(err.isVaultError) {
// This an error from Vault API
// Check Vault hint on this error
console.log(err.vaultHelpMessage);
}
else {
// Here is still the full Axios error, e.g. err.isAxiosError, err.response, err.request
// This allows handling of network/tls related issues
// Or just re-kthrow if you don't care
throw err;
}
}
`

Check below docs for more information on specific function groups.

$3

| Group | Type | Default mount point | Link |
|:------------------|:------------------|:------------------|:--------------:|
| Active Directory (AD) - deprecated | Secret engine | /ad | Doc file |
| AppRole | Auth method | /auth/approle | Doc file |
| LDAP | Auth method | /auth/ldap | Doc file |
| Kubernetes | Auth method | /auth/kubernetes | Doc file |
| KV v2 | Secret engine | /kv | Doc file |
| PKI | Secret engine | /pki | Doc file |
| System Backend | System | General operations | Doc file |
| System Backend | System | SEAL operations | Doc file |
| TLS Certificate | Auth method | /auth/cert | Doc file |
| Token | Auth method | /auth/token | Doc file |
| TOTP | Secret engine | /totp | Doc file |
| Userpass | Auth method | /auth/userpass | Doc file |
| | | | |

$3

The following HashiCorp Vault API endpoints are currently covered:

* System Backend - Partially

* Auth methods:

| Method | Coverage status |
|:-----------|:-----------|
| AppRole | Partially |
| LDAP | All endpoints |
| Userpass | All endpoints |
| Kubernetes | All endpoints |
| TLS Cert | Partially |
| Token | Most of them |
| | |

* Secret engines:

| Engine | Coverage status |
|:------------|:-----------|
| Active Directory (AD) | Most of them, currently in deprecation notice |
| KV Version 2 | All endpoints |
| PKI | Most of them |
| TOTP | Few of them|
| | |

$3

* Follow the detailed instructions from this doc

$3

* HashiCorp Vault Using KV engine doc

* HashiCorp Vault Docker Hub page

* Ruan Bekker's Blog post

$3

If you want to contribute to the module and make it better, your help is very welcome. You can do so submitting a Pull Request. It will be reviewed and merged to main branch if accepted.

By contributing to this public repository, you fully agree with the following Developer's Certificate of Origin document.

$3

If you have found what you believe to be an issue with hashi-vault-js` please do not hesitate to file an issue on the GitHub repository here.

$3

If you want to see new features or enhancements to the current ones, we would love to hear them. Please submit an issue on the GitHub repository here.

$3

Written by Rod Anami , June 2020.

$3

* Richard
* Ordinary IT9
* Osama Adil
* Jose

$3

This project is licensed under the MIT license.

HashiCorp Vault is licensed under the Business Source License 1.1.