node-vault-client 2.0.1 → 2.1.0

package/README.md

@@ -47,14 +47,16 @@ vaultClient.read('secret/tst').then(lease => {
 
 ```javascript
 const vaultClient = VaultClient.boot('main', {
-    api: { url: 'https://vault.example.com:8200/' },
+    api: {
+        url: 'https://vault.example.com:8200/',
+        namespace: 'some_namespace',                   // Optional. X-Vault-Namespace header (canonical location; auth.config.namespace is honored as a legacy fallback)
+    },
     auth: {
         type: 'iam',
         mount: 'aws',                                  // Optional. Vault AWS auth mount point ("aws" by default)
         config: {
             role: 'my_iam_role',
             iam_server_id_header_value: 'https://vault.example.com:8200/', // Optional. X-Vault-AWS-IAM-Server-ID header
-            namespace: 'some_namespace',               // Optional. X-Vault-Namespace header
             region: 'eu-central-1',                     // Optional. AWS STS region (see below)
             credentials: {                             // Optional. Resolved from the AWS provider chain when omitted
                 accessKeyId: process.env.AWS_ACCESS_KEY_ID,
@@ -136,6 +138,14 @@ const vaultClient = VaultClient.boot('main', {
         * [.read(path)](#VaultClient+read) ⇒ <code>Promise.&lt;Lease&gt;</code>
         * [.list(path)](#VaultClient+list) ⇒ <code>Promise.&lt;Lease&gt;</code>
         * [.write(path, data)](#VaultClient+write) ⇒ <code>Promise.&lt;Object&gt;</code>
+        * [.delete(path)](#VaultClient+delete) ⇒ <code>Promise.&lt;Object&gt;</code>
+        * [.update(path, data)](#VaultClient+update) ⇒ <code>Promise.&lt;Object&gt;</code>
+        * [.request(method, path, [data])](#VaultClient+request) ⇒ <code>Promise.&lt;Object&gt;</code>
+        * [.deleteVersions(path, versions)](#VaultClient+deleteVersions) ⇒ <code>Promise.&lt;Object&gt;</code>
+        * [.undeleteVersions(path, versions)](#VaultClient+undeleteVersions) ⇒ <code>Promise.&lt;Object&gt;</code>
+        * [.destroyVersions(path, versions)](#VaultClient+destroyVersions) ⇒ <code>Promise.&lt;Object&gt;</code>
+        * [.readMetadata(path)](#VaultClient+readMetadata) ⇒ <code>Promise.&lt;Object&gt;</code>
+        * [.deleteMetadata(path)](#VaultClient+deleteMetadata) ⇒ <code>Promise.&lt;Object&gt;</code>
         * [.close()](#VaultClient+close)
     * _static_
         * [.boot(name, [options])](#VaultClient.boot) ⇒ <code>VaultClient</code>
@@ -143,6 +153,11 @@ const vaultClient = VaultClient.boot('main', {
         * [.clear([name])](#VaultClient.clear)
 * [Lease](#Lease)
 
+**Return contract**: [`read()`](#VaultClient+read) and [`list()`](#VaultClient+list) resolve to a
+[`Lease`](#Lease) — use its accessors to extract the secret data. Every other data-plane method
+(`write`, `delete`, `update`, `request` and the KV v2 helpers) resolves to the raw parsed Vault
+response body, which may be empty/undefined for `204 No Content` responses.
+
 <a name="new_VaultClient_new"></a>
 
 #### new VaultClient(options)
@@ -156,12 +171,15 @@ Client constructor function.
 | options.api.url | <code>String</code> |  | the url of the vault server |
 | [options.api.apiVersion] | <code>String</code> | `v1` |  |
 | [options.api.requestOptions] | <code>Object</code> |  | extra options merged into every HTTP request (see [Custom transport](#custom-transport-proxy--self-signed-tls)) |
+| [options.api.namespace] | <code>String</code> |  | Optional. Vault namespace, sent as the `X-Vault-Namespace` header on **every** request — login, token lookup/renewal, and all secret operations — for every auth type. This is the canonical location; `auth.config.namespace` is still honored for backward compatibility. |
+| [options.api.kv.autoDetect] | <code>boolean</code> | `false` | auto-detect the KV version of each mount on first use (see [KV v2 & generic backends](#kv-v2--generic-backends)) |
+| [options.api.engines] | <code>Object</code> | `{}` | static mount-to-version map, e.g. `{ secret: 2, legacy: 1 }` (see [KV v2 & generic backends](#kv-v2--generic-backends)) |
 | options.auth | <code>Object</code> |  |  |
 | options.auth.type | <code>String</code> |  |  |
 | [options.auth.mount] | <code>String</code> |  | Vault auth backend mount point; default varies per method (e.g. "aws" for iam, "approle", "token", "kubernetes") |
 | options.auth.config | <code>Object</code> |  | auth configuration variables |
-| [options.auth.config.namespace] | <code>String</code> |  | Optional. Vault namespace, sent as the `X-Vault-Namespace` header on all secret read/list/write requests. Applies to every auth type, not just IAM. |
-| options.logger | <code>Object</code> | `false` |  | Logger that supports "error", "info", "warn", "trace", "debug" methods. Uses `console` by default. Pass `false` to disable logging. |
+| [options.auth.config.namespace] | <code>String</code> |  | Optional. Legacy location for the Vault namespace (see `api.namespace`). Sent as the `X-Vault-Namespace` header on **every** request for every auth type. |
+| [options.logger] | <code>Object</code> \| <code>false</code> |  | Logger that supports "error", "info", "warn", "trace", "debug" methods. Uses `console` by default. Pass `false` to disable logging. |
 
 ##### Custom transport (proxy / self-signed TLS)
 
@@ -196,6 +214,8 @@ env var with no code change. Only disable verification
 (`new Agent({ connect: { rejectUnauthorized: false } })`) in throwaway/dev setups — it removes
 MITM protection.
 
+<a name="VaultClient+fillNodeConfig"></a>
+
 #### vaultClient.fillNodeConfig() ⇒ <code>Promise</code>
 Populates Vault's values to NPM "config" module
 
@@ -236,9 +256,131 @@ Resolves to the raw parsed Vault response body, which may be empty/undefined for
 
 | Param | Type | Description |
 | --- | --- | --- |
-| path |  | path used to write data |
+| path | <code>string</code> | path used to write data |
 | data | <code>object</code> | data to write |
 
+<a name="VaultClient+delete"></a>
+
+#### vaultClient.delete(path) ⇒ <code>Promise.&lt;Object&gt;</code>
+Deletes a secret
+
+On KV v2 mounts this sends `DELETE` to the `data/` path, soft-deleting the latest version.
+On KV v1 / non-KV mounts this sends `DELETE` to the raw path. Resolves to the raw parsed
+Vault response body, which may be empty/undefined for `204 No Content` responses.
+
+**Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>string</code> | path to the secret |
+
+<a name="VaultClient+update"></a>
+
+#### vaultClient.update(path, data) ⇒ <code>Promise.&lt;Object&gt;</code>
+Updates (merge-patches) a KV v2 secret
+
+Sends `PATCH` with `Content-Type: application/merge-patch+json`, merging `data` into the
+existing secret without overwriting keys that are not listed. KV v2 merge-patch operation —
+KV v1 mounts do not support `PATCH` and Vault returns `405` there. Resolves to the raw
+parsed Vault response body.
+
+**Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>string</code> | path to the secret |
+| data | <code>object</code> | keys to merge into the existing secret |
+
+<a name="VaultClient+request"></a>
+
+#### vaultClient.request(method, path, [data]) ⇒ <code>Promise.&lt;Object&gt;</code>
+Raw request — escape hatch for any Vault backend
+
+Sends the literal API path with no KV path rewriting and no response unwrapping, and
+resolves to the parsed response body. Use it for non-KV backends (e.g. Transit) or when you
+have already constructed the complete Vault API path.
+
+**Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| method | <code>string</code> | HTTP method (e.g. `GET`, `POST`) |
+| path | <code>string</code> | literal API path, sent as-is |
+| [data] | <code>object</code> | request body |
+
+<a name="VaultClient+deleteVersions"></a>
+
+#### vaultClient.deleteVersions(path, versions) ⇒ <code>Promise.&lt;Object&gt;</code>
+Soft-deletes specific versions of a KV v2 secret
+
+KV v2 only — rejects with `UnsupportedOperationError` on non-v2 mounts. Resolves to the raw
+parsed Vault response body.
+
+**Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>string</code> | path to the secret |
+| versions | <code>Array.&lt;number&gt;</code> | version numbers to soft-delete |
+
+<a name="VaultClient+undeleteVersions"></a>
+
+#### vaultClient.undeleteVersions(path, versions) ⇒ <code>Promise.&lt;Object&gt;</code>
+Undeletes (restores) soft-deleted versions of a KV v2 secret
+
+KV v2 only — rejects with `UnsupportedOperationError` on non-v2 mounts. Resolves to the raw
+parsed Vault response body.
+
+**Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>string</code> | path to the secret |
+| versions | <code>Array.&lt;number&gt;</code> | version numbers to restore |
+
+<a name="VaultClient+destroyVersions"></a>
+
+#### vaultClient.destroyVersions(path, versions) ⇒ <code>Promise.&lt;Object&gt;</code>
+Permanently destroys specific versions of a KV v2 secret
+
+The destroyed version data cannot be recovered. KV v2 only — rejects with
+`UnsupportedOperationError` on non-v2 mounts. Resolves to the raw parsed Vault response body.
+
+**Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>string</code> | path to the secret |
+| versions | <code>Array.&lt;number&gt;</code> | version numbers to destroy |
+
+<a name="VaultClient+readMetadata"></a>
+
+#### vaultClient.readMetadata(path) ⇒ <code>Promise.&lt;Object&gt;</code>
+Reads KV v2 metadata for a secret
+
+Resolves to the metadata document (`current_version`, the `versions` map, timestamps, etc.).
+KV v2 only — rejects with `UnsupportedOperationError` on non-v2 mounts.
+
+**Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>string</code> | path to the secret |
+
+<a name="VaultClient+deleteMetadata"></a>
+
+#### vaultClient.deleteMetadata(path) ⇒ <code>Promise.&lt;Object&gt;</code>
+Deletes all metadata and version history for a KV v2 secret (permanent)
+
+KV v2 only — rejects with `UnsupportedOperationError` on non-v2 mounts. Resolves to the raw
+parsed Vault response body, which may be empty/undefined for `204 No Content` responses.
+
+**Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| path | <code>string</code> | path to the secret |
+
 <a name="VaultClient+close"></a>
 
 #### vaultClient.close()
@@ -315,6 +457,152 @@ If no name passed all named instances will be cleared.
 | --- | --- | --- |
 | [name] | <code>String</code> | Vault instance name, all instances will be cleared if no name were passed |
 
+## KV v2 & generic backends
+
+### Overview
+
+By default the client behaves exactly as before (KV v1 / raw passthrough). To enable transparent
+KV v2 support set `api.kv.autoDetect: true` **or** supply a static `api.engines` map. Either
+option activates path-rewriting and response-unwrapping; callers do not need to know the engine
+version.
+
+### Configuration options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `api.kv.autoDetect` | `boolean` | `false` | Auto-detect the KV version of each mount on first use via `GET sys/internal/ui/mounts/<path>`. |
+| `api.engines` | `Object` | `{}` | Static mount-to-version map, e.g. `{ secret: 2, legacy: 1 }`. Overrides detection; use this when the token lacks permission on `sys/internal/ui/mounts`. |
+
+Both options can be combined: `engines` acts as an override — matching mounts skip detection
+while unmatched mounts are auto-detected (when `autoDetect: true`).
+
+### Auto-detect example
+
+```javascript
+const client = VaultClient.boot('main', {
+    api: {
+        url: 'https://vault.example.com:8200/',
+        kv: { autoDetect: true },
+    },
+    auth: { type: 'token', config: { token: '...' } },
+});
+
+// Works transparently on both KV v1 and KV v2 mounts
+const lease = await client.read('secret/my-app/config');
+console.log(lease.getData());         // the secret object
+console.log(lease.getMetadata());     // KV v2 version metadata (undefined on v1)
+```
+
+### Static engines override example
+
+```javascript
+const client = VaultClient.boot('main', {
+    api: {
+        url: 'https://vault.example.com:8200/',
+        engines: { secret: 2, legacy: 1 },
+    },
+    auth: { type: 'token', config: { token: '...' } },
+});
+```
+
+### KV v2-specific methods
+
+These methods require a KV v2 mount and throw `UnsupportedOperationError` on v1 / non-KV mounts.
+
+```javascript
+// Soft-delete specific versions
+await client.deleteVersions('secret/foo', [1, 2]);
+
+// Restore soft-deleted versions
+await client.undeleteVersions('secret/foo', [1]);
+
+// Permanently destroy versions
+await client.destroyVersions('secret/foo', [1, 2]);
+
+// Read version metadata (current_version, versions map, etc.)
+const meta = await client.readMetadata('secret/foo');
+
+// Delete all metadata and version history (permanent)
+await client.deleteMetadata('secret/foo');
+```
+
+### update() — merge-patch
+
+```javascript
+// PATCH a subset of keys without overwriting others (KV v2)
+await client.update('secret/foo', { password: 'new-value' });
+// Sends PATCH secret/data/foo with Content-Type: application/merge-patch+json
+```
+
+### delete()
+
+```javascript
+// Soft-delete the latest version on KV v2; DELETE on v1/passthrough
+await client.delete('secret/foo');
+```
+
+### request() — raw escape hatch
+
+For any Vault backend that does not benefit from KV path rewriting use `request()`. It sends the
+literal path with no rewriting or response normalisation and returns the parsed body directly.
+
+```javascript
+// Encrypt with Transit engine — path must not be rewritten
+const result = await client.request('POST', 'transit/encrypt/my-key', {
+    plaintext: Buffer.from('hello').toString('base64'),
+});
+console.log(result.data.ciphertext);
+```
+
+### Lease.getMetadata()
+
+`getMetadata()` is additive — existing code is unaffected.
+
+```javascript
+const lease = await client.read('secret/my-app/db');
+lease.getData();     // the secret values
+lease.getMetadata(); // { version, created_time, deletion_time, destroyed, custom_metadata }
+                     // undefined on KV v1 / passthrough mounts
+```
+
+### Path requirements when autoDetect / engines are active
+
+When `autoDetect: true` or `api.engines` is set, the client rewrites logical paths to the
+correct KV v2 API paths automatically (e.g. `secret/foo` → `secret/data/foo` for reads).
+**Callers must pass logical paths — do not include the internal KV v2 segments** (`data/`,
+`metadata/`, `delete/`, `undelete/`, `destroy/`) in the path argument:
+
+```javascript
+// Correct — logical path only
+await client.read('secret/my-app/config');
+
+// Wrong — double-rewrite: 'secret/data/foo' becomes 'secret/data/data/foo' on the wire
+await client.read('secret/data/foo');
+```
+
+If you need to send a fully-literal Vault API path (e.g. when working with non-KV backends or
+when you have already constructed the complete path), use `request()` which bypasses all path
+rewriting:
+
+```javascript
+// Literal path, no rewriting
+await client.request('GET', 'secret/data/foo');
+```
+
+### Mount detection caching
+
+- Each canonical mount is detected at most once per `VaultClient` instance.
+- Concurrent first-touch requests for the same mount share a single in-flight detection promise.
+- The detection endpoint used is `GET sys/internal/ui/mounts/<path>` (readable by any authenticated token).
+- When the token lacks permission on that endpoint, set `api.engines` to skip detection.
+
+### Error classes
+
+| Class | When thrown |
+|---|---|
+| `UnsupportedOperationError` | A v2-only method (`deleteVersions`, `undeleteVersions`, `destroyVersions`, `readMetadata`, `deleteMetadata`) is called against a non-v2 mount. |
+| `VaultError` | Mount detection fails (e.g. permission denied) and no `api.engines` override was provided. |
+
 ## Contributing
 
 Contributions are welcome! Please read the [contributing guide](CONTRIBUTING.md) to get started,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-vault-client",
-  "version": "2.0.1",
+  "version": "2.1.0",
   "description": "A Vault Client implemented in pure javascript for HashiCorp Vault. It supports variety of Auth Backends and performs lease renewal for issued auth token.",
   "repository": {
     "url": "git+https://github.com/namecheap/node-vault-client.git"
@@ -15,9 +15,10 @@
   "scripts": {
     "test": "mocha --exit \"test/**/*.test.mjs\"",
     "test:unit": "mocha \"test/*.test.mjs\"",
-    "test:e2e": "mocha --exit \"test/e2e/**/*.test.mjs\"",
+    "test:e2e": "mocha --exit \"test/e2e/e2e.test.mjs\"",
+    "test:e2e:kv2": "mocha --exit \"test/e2e/e2e.kv2.test.mjs\"",
     "coverage": "c8 npm run test:unit",
-    "lint": "eslint src/",
+    "lint": "eslint src/ test/",
     "version": "git add -A ."
   },
   "c8": {
@@ -29,14 +30,18 @@
       "html",
       "lcov"
     ],
-    "all": true
+    "all": true,
+    "check-coverage": true,
+    "statements": 97,
+    "branches": 93,
+    "functions": 100,
+    "lines": 97
   },
   "author": "Namecheap <opensource@namecheap.com>",
   "license": "Apache-2.0",
   "dependencies": {
     "@aws-sdk/credential-providers": "^3.382.0",
     "aws4": "^1.8.0",
-    "lodash": "^4.17.21",
     "long-timeout": "^0.1.1"
   },
   "peerDependencies": {
@@ -45,7 +50,9 @@
   "overrides": {
     "serialize-javascript": "^7.0.5",
     "glob": "^13.0.0",
-    "diff": "^8.0.3"
+    "diff": "^8.0.3",
+    "brace-expansion": "^5.0.8",
+    "js-yaml": "^4.3.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
@@ -54,6 +61,7 @@
     "deep-freeze": "^0.0.1",
     "eslint": "^9.39.4",
     "globals": "^17.6.0",
+    "lodash": "^4.17.21",
     "mocha": "^11.7.6",
     "sinon": "^22.0.0",
     "sinon-chai": "^4.0.0"

package/src/Lease.js

@@ -1,20 +1,20 @@
 'use strict';
 
-const _ = require('lodash');
-
 class Lease {
     constructor(
         requestId,
         leaseId,
         leaseDuration,
         renewable,
-        data
+        data,
+        metadata
     ) {
         this.__requestId = requestId;
         this.__leaseId = leaseId;
         this.__leaseDuration = leaseDuration;
         this.__renewable = renewable;
         this.__data = data === undefined ? {} : data;
+        this.__metadata = metadata;
     }
 
     static fromResponse(response) {
@@ -23,7 +23,8 @@ class Lease {
             response.lease_id,
             response.lease_duration,
             response.renewable,
-            response.data
+            response.data,
+            response.metadata
         );
     }
 
@@ -43,7 +44,7 @@ class Lease {
      * @returns {Object}
      */
     getData() {
-        return _.cloneDeep(this.__data);
+        return structuredClone(this.__data);
     }
 
     /**
@@ -52,6 +53,16 @@ class Lease {
     isRenewable() {
         return this.__renewable;
     }
+
+    /**
+     * KV v2 version metadata object (created_time, version, etc.).
+     * Returns undefined for KV v1 / non-KV leases.
+     *
+     * @returns {Object|undefined}
+     */
+    getMetadata() {
+        return this.__metadata;
+    }
 }
 
 module.exports = Lease;