npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

hashi-vault-js

v0.4.16

Published

A node.js module to interact with the Hashicorp Vault API.

Downloads

59,387

Readme

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 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: v18.x
    • Recommended: v20.x
  • npm
    • Tested on: v10.8.x
  • HashiCorp Vault
    • Minimum: v1.15.x
    • Accepted: v1.16.x
    • Recommended: v1.17.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

npm install hashi-vault-js --save

Uninstall

npm uninstall hashi-vault-js

Release notes and versions

Change log

Class Constructor

{
  // 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'
}

Module usage

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

  • Production
const Vault = require('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
const Vault = require('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:

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:

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:

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:

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:

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:

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

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

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

Create a new secret in the Vault:

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:

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

Update secret version 1 in the Vault:

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

TypeScript

hashi-vault-js includes TypeScript definitions in the Vault.d.ts.

let response: ReadKVSecretResponse = null;
try {
  const { data } = await vault.readKVSecret(token, Item.name);
  response = data;
}

Mount points

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:

vault secrets enable -path=knight kv-v2

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

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

Error handling

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.

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.

Available functions

| Group | Type | Default mount point | Link | |:------------------|:------------------|:------------------|:--------------:| | Active Directory (AD) - deprectated | 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 | | | | | |

Coverage and limitations

The following HashiCorp Vault API endpoints are currently covered:

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

Test environment

  • Follow the detailed instructions from this doc

References

  • HashiCorp Vault Using KV engine doc

  • HashiCorp Vault Docker Hub page

  • Ruan Bekker's Blog post

Contributing

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.

Reporting an issue

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.

Suggesting a new feature

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.

Authors

Written by Rod Anami [email protected], June 2020.

Contributors

  • Richard <richie765@>
  • Ordinary IT9 <hkgnobody@>
  • Osama Adil [email protected]
  • Jose <josedev-union@>

License

This project is licensed under the MIT license.

HashiCorp Vault is licensed under the Business Source License 1.1.