node-vault-client 1.0.2 → 1.0.3

package/README.md

@@ -29,6 +29,114 @@ vaultClient.read('secret/tst').then(v => {
 }).catch(e => console.error(e));
 ```
 
+## KV v2 support
+
+This release adds transparent support for the [KV v2 secrets engine](https://developer.hashicorp.com/vault/docs/secrets/kv/kv-v2)
+on top of the existing KV v1 / raw passthrough behaviour.
+
+**It is fully opt-in and non-breaking.** With no extra configuration the client behaves exactly as
+before: every path is treated as KV v1 / raw passthrough and no extra request is made. KV v2 is
+activated per mount by setting `api.kv.autoDetect: true` **or** by supplying a static `api.engines`
+map. Once enabled, the client rewrites paths (`secret/foo` → `secret/data/foo`) and unwraps the
+nested KV v2 response automatically — callers never deal with the `data/` / `metadata/` segments
+themselves.
+
+### 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>`. The result is cached per mount for the lifetime of the client. |
+| `api.engines` | `Object` | `{}` | Static mount-to-version map, e.g. `{ secret: 2, legacy: 1 }`. Listed mounts resolve with no detection round-trip; use this when the token lacks permission on `sys/internal/ui/mounts`. |
+
+`engines` always takes precedence over detection, so the two can be combined: matching mounts use
+the map while unmatched mounts are auto-detected (when `autoDetect: true`) or treated as v1.
+
+### KV v1 (default — nothing to configure)
+
+```javascript
+const client = VaultClient.boot('main', {
+    api: { url: 'https://vault.example.com:8200/' },
+    auth: { type: 'token', config: { token: '...' } },
+});
+
+const lease = await client.read('secret/my-app/config'); // GET secret/my-app/config
+console.log(lease.getData());      // the secret object
+console.log(lease.getMetadata());  // undefined on KV v1
+```
+
+### KV v2
+
+Pass **logical** paths only — the client inserts the `data/` (and `metadata/` for `list`) segment
+for you.
+
+```javascript
+const client = VaultClient.boot('main', {
+    api: {
+        url: 'https://vault.example.com:8200/',
+        engines: { secret: 2 },          // or: kv: { autoDetect: true }
+    },
+    auth: { type: 'token', config: { token: '...' } },
+});
+
+// read  → GET    secret/data/my-app/config, response.data.data is unwrapped automatically
+const lease = await client.read('secret/my-app/config');
+console.log(lease.getData());      // the secret values
+console.log(lease.getMetadata());  // { version, created_time, ... } on KV v2
+
+// write → POST   secret/data/my-app/config with { data: { ... } } wrapping done for you
+await client.write('secret/my-app/config', { password: 's3cr3t' });
+
+// list  → LIST   secret/metadata/my-app
+await client.list('secret/my-app');
+```
+
+### Mixed v1 + v2 mounts on one client
+
+Version resolution is **per mount**, so a single client can talk to v1 and v2 mounts at the same
+time. List each mount's version in `api.engines`:
+
+```javascript
+const client = VaultClient.boot('main', {
+    api: {
+        url: 'https://vault.example.com:8200/',
+        engines: {
+            'secret-v2': 2,   // KV v2 mount
+            // 'secret' is not listed → treated as KV v1 (passthrough)
+        },
+    },
+    auth: { type: 'token', config: { token: '...' } },
+});
+
+await client.read('secret/legacy/app');        // v1 → GET secret/legacy/app
+await client.read('secret-v2/app/config');     // v2 → GET secret-v2/data/app/config
+await client.read('database/creds/app-role');  // not KV  → passthrough, GET as-is
+```
+
+Or let the client figure it out with `autoDetect` (requires the token to read
+`sys/internal/ui/mounts`):
+
+```javascript
+const client = VaultClient.boot('main', {
+    api: { url: 'https://vault.example.com:8200/', kv: { autoDetect: true } },
+    auth: { type: 'token', config: { token: '...' } },
+});
+
+await client.read('secret/legacy/app');     // detected as v1
+await client.read('secret-v2/app/config');  // detected as v2
+```
+
+### Notes & caveats
+
+- **Do not include KV v2 segments in the path.** Pass `secret/foo`, not `secret/data/foo` — the
+  latter would be rewritten to `secret/data/data/foo` on a v2 mount.
+- **Vault policy must allow the v2 paths.** KV v2 reads hit `<mount>/data/...` (and `list` hits
+  `<mount>/metadata/...`), so the auth token's policy must grant capabilities on those paths, not
+  on the logical path.
+- Non-KV backends (database, transit, etc.) are always treated as passthrough — leave them out of
+  `api.engines`, and `autoDetect` recognises them as non-KV automatically.
+- If detection fails (e.g. permission denied) and no `api.engines` override matches, the read
+  rejects with a `VaultError` — set `api.engines` to bypass detection in that case.
+
 ## Supported Auth Backends
 
 * [AWS IAM](https://www.vaultproject.io/docs/auth/aws.html#iam-auth-method)
@@ -65,6 +173,9 @@ Client constructor function.
 | options.api | <code>Object</code> |  |  |
 | options.api.url | <code>String</code> |  | the url of the vault server |
 | [options.api.apiVersion] | <code>String</code> | `v1` |  |
+| [options.api.kv] | <code>Object</code> |  | KV engine options |
+| [options.api.kv.autoDetect] | <code>boolean</code> | `false` | Auto-detect the KV version per mount via `GET sys/internal/ui/mounts/<path>`. |
+| [options.api.engines] | <code>Object</code> | `{}` | Static mount-to-version map, e.g. `{ secret: 2, legacy: 1 }`. Overrides detection. |
 | options.auth | <code>Object</code> |  |  |
 | options.auth.type | <code>String</code> |  |  |
 | options.auth.config | <code>Object</code> |  | auth configuration variables |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-vault-client",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "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"

package/src/Lease.js

@@ -8,13 +8,15 @@ class Lease {
         leaseId,
         leaseDuration,
         renewable,
-        data
+        data,
+        metadata
     ) {
         this.__requestId = requestId;
         this.__leaseId = leaseId;
         this.__leaseDuration = leaseDuration;
         this.__renewable = renewable;
-        this.__data = data === undefined ? {} : data;
+        this.__data = (data === undefined || data === null) ? {} : data;
+        this.__metadata = metadata;
     }
 
     static fromResponse(response) {
@@ -23,7 +25,8 @@ class Lease {
             response.lease_id,
             response.lease_duration,
             response.renewable,
-            response.data
+            response.data,
+            response.metadata
         );
     }
 
@@ -52,6 +55,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;

package/src/MountResolver.js

@@ -0,0 +1,167 @@
+'use strict';
+
+const { VaultError } = require('./errors');
+
+/**
+ * Resolves the KV engine version for a given secret path.
+ *
+ * Responsibilities:
+ *  1. Check engines override map first (longest-prefix match, no I/O).
+ *  2. Auto-detect via detectFn(path) -> { data: { path, type, options } }.
+ *  3. Cache by canonical mount path; de-duplicate in-flight detections.
+ *  4. On failure, throw VaultError with actionable guidance.
+ *
+ * @param {Function} detectFn          - async (path: string) => Vault mount-info response
+ * @param {Object}   enginesOverride   - { [mountPrefix]: version }
+ * @param {Object}   logger            - logger with .debug(), .error() etc.
+ * @param {Object}   [opts]            - additional options
+ * @param {boolean}  [opts.disabled]   - if true, always return passthrough (version 1)
+ */
+class MountResolver {
+    constructor(detectFn, enginesOverride, logger, opts) {
+        this.__detectFn = detectFn;
+        this.__engines = enginesOverride || {};
+        this.__log = logger;
+        this.__disabled = opts && opts.disabled === true;
+
+        // Cache: canonical mount path (no trailing slash) -> { mount, version, type }
+        this.__cache = new Map();
+        // In-flight promises: canonical mount path -> Promise<{mount,version,type}>
+        this.__inflight = new Map();
+    }
+
+    /**
+     * Resolve the engine version for the given path.
+     *
+     * @param {string} path - full logical path (e.g. "secret/foo/bar")
+     * @returns {Promise<{mount: string, version: number, type: string}>}
+     */
+    resolve(path) {
+        // 1. Check engines override (longest-prefix match). This applies even when
+        //    auto-detection is disabled, so listed mounts resolve with no I/O.
+        const override = this.__enginesOverrideLookup(path);
+        if (override !== null) {
+            this.__log.debug('MountResolver: engines override for %s -> v%d', path, override.version);
+            return Promise.resolve(override);
+        }
+
+        // 2. When detection is disabled (autoDetect off), an unlisted mount is a
+        //    passthrough (v1) — never issue a sys/internal/ui/mounts round-trip.
+        //    engines is the documented fallback for Vaults that deny detection.
+        if (this.__disabled) {
+            return Promise.resolve({ mount: this.__extractMount(path), version: 1, type: 'kv' });
+        }
+
+        // 3. Auto-detect: use canonical mount path as cache key once we know it.
+        //    For the in-flight grouping key we use the first path segment so that
+        //    concurrent reads of sub-paths of the SAME mount (e.g. secret/a and
+        //    secret/b) share one detection.  After the shared promise resolves we
+        //    verify that the canonical mount returned actually prefixes this path;
+        //    if it does not (two distinct multi-segment mounts share a first segment,
+        //    e.g. team/kvA/* and team/kvB/*), we start a fresh detection using the
+        //    full path as key so each mount gets its own call.
+        const interimKey = path.split('/')[0];
+        return this.__detectWithCache(interimKey, path);
+    }
+
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+
+    /**
+     * Longest-prefix match against the engines override map.
+     * Returns { mount, version } or null if no match found.
+     */
+    __enginesOverrideLookup(path) {
+        const entries = Object.entries(this.__engines);
+        if (entries.length === 0) return null;
+
+        // Sort by descending key length (longest first) for prefix match
+        entries.sort((a, b) => b[0].length - a[0].length);
+
+        for (const [prefix, version] of entries) {
+            const normalised = prefix.replace(/\/+$/, '');
+            if (path === normalised || path.startsWith(normalised + '/')) {
+                return { mount: normalised, version: Number(version), type: 'kv' };
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Resolve via cache or detectFn.  Groups concurrent calls by interimKey so
+     * only one detectFn call is in-flight per first-segment at a time.
+     *
+     * Followers that join a shared in-flight promise verify that the resolved
+     * canonical mount actually prefixes their path.  If it does not (two distinct
+     * multi-segment mounts share a first segment, e.g. "team/kvA" and "team/kvB"),
+     * the follower falls through to start its own fresh detection keyed on its
+     * full path, so each mount gets its own accurate detection result.
+     */
+    __detectWithCache(interimKey, path) {
+        // Check persistent cache first (keyed on canonical mount path)
+        for (const [mountKey, entry] of this.__cache) {
+            if (path === mountKey || path.startsWith(mountKey + '/')) {
+                return Promise.resolve(entry);
+            }
+        }
+
+        // Check in-flight for this interim key (first segment or full path)
+        if (this.__inflight.has(interimKey)) {
+            // Join the existing in-flight promise but verify the result matches our path.
+            // If the detection was for a different sub-mount, start a fresh detection.
+            return this.__inflight.get(interimKey).then((entry) => {
+                if (path === entry.mount || path.startsWith(entry.mount + '/')) {
+                    return entry;
+                }
+                // The shared detection resolved to a different mount — start our own.
+                // Use the full path as key so it won't collide with the first-segment key.
+                return this.__detectWithCache(path, path);
+            });
+        }
+
+        // Start a new detection
+        const promise = this.__detectFn(path)
+            .then((response) => {
+                const info = response && response.data;
+                if (!info) {
+                    throw new Error('Unexpected empty detection response');
+                }
+
+                const canonicalMount = (info.path || interimKey).replace(/\/+$/, '');
+                const type = info.type || 'unknown';
+                const optVersion = info.options && info.options.version;
+                // Only kv v2 gets special treatment; everything else is passthrough
+                const version = (type === 'kv' && Number(optVersion) === 2) ? 2 : 1;
+
+                const entry = { mount: canonicalMount, version, type };
+                this.__log.debug('MountResolver: detected %s as type=%s version=%d', canonicalMount, type, version);
+
+                // Store in persistent cache
+                this.__cache.set(canonicalMount, entry);
+                // Clear in-flight
+                this.__inflight.delete(interimKey);
+                return entry;
+            })
+            .catch((err) => {
+                // Clear in-flight so callers can retry
+                this.__inflight.delete(interimKey);
+                throw new VaultError(
+                    `Failed to detect KV engine version for mount "${interimKey}" (path: ${path}): ${err.message}. ` +
+                    'Set api.engines or disable autoDetect to bypass detection.'
+                );
+            });
+
+        this.__inflight.set(interimKey, promise);
+        return promise;
+    }
+
+    /**
+     * Simple first-segment extraction used only for the disabled path.
+     */
+    __extractMount(path) {
+        return path.split('/')[0];
+    }
+}
+
+module.exports = MountResolver;

package/src/VaultClient.js

@@ -9,6 +9,8 @@ const VaultTokenAuth = require('./auth/VaultTokenAuth');
 const VaultIAMAuth = require('./auth/VaultIAMAuth');
 const VaultNodeConfig = require('./VaultNodeConfig');
 const VaultKubernetesAuth = require('./auth/VaultKubernetesAuth');
+const MountResolver = require('./MountResolver');
+const { rewritePath, normalizeResponse } = require('./kvTransform');
 const vaultInstances = {};
 
 class VaultClient {
@@ -20,6 +22,14 @@ class VaultClient {
      * @param {Object} options.api
      * @param {String} options.api.url - the url of the vault server
      * @param {String} [options.api.apiVersion='v1']
+     * @param {Object} [options.api.kv] - KV engine options
+     * @param {boolean} [options.api.kv.autoDetect=false] - When true, auto-detect the KV version per mount
+     *      via a `sys/internal/ui/mounts/<path>` round-trip. When false (default) no detection call is
+     *      ever made and read/list/write behave byte-for-byte as before unless an engine is
+     *      listed in `options.api.engines`.
+     * @param {Object} [options.api.engines] - Static mount-to-version overrides, e.g. `{ secret: 2, legacy: 1 }`.
+     *      Listed mounts resolve without any detection round-trip (works even with autoDetect off), making
+     *      this a reliable fallback for Vaults that deny the detection endpoint.
      * @param {Object} options.auth
      * @param {String} options.auth.type
      * @param {Object} options.auth.config - auth configuration variables
@@ -43,6 +53,25 @@ class VaultClient {
         );
 
         this.__namespace = options.auth.config.namespace;
+
+        // KV v2 support (opt-in, non-breaking).
+        const kvOpts = (options.api && options.api.kv) || {};
+        const autoDetect = kvOpts.autoDetect === true;
+        const engines = (options.api && options.api.engines) || {};
+
+        // Detection (the sys/internal/ui/mounts round-trip) only happens when
+        // autoDetect is on. With engines set but autoDetect off, listed mounts use
+        // the override and any other mount is passthrough (v1) — no detection call
+        // is ever made. This keeps the default byte-for-byte and makes engines a
+        // working fallback for Vaults that deny the detection endpoint.
+        const resolverDisabled = !autoDetect;
+
+        // Build detectFn lazily — it uses __auth and __api which are already set above.
+        const detectFn = (path) => this.__detectMount(path);
+
+        this.__resolver = new MountResolver(detectFn, engines, this.__log, {
+            disabled: resolverDisabled,
+        });
     }
 
     /**
@@ -173,6 +202,81 @@ class VaultClient {
         return {'X-Vault-Token': token.getId()}
     }
 
+    // -------------------------------------------------------------------------
+    // Detection helper (used by MountResolver's detectFn)
+    // -------------------------------------------------------------------------
+
+    /**
+     * Calls GET sys/internal/ui/mounts/<path> with the current auth token.
+     * Returns the parsed Vault response body.
+     * @private
+     */
+    __detectMount(path) {
+        return this.__auth.getAuthToken()
+            .then((token) => {
+                const detectPath = `sys/internal/ui/mounts/${path}`;
+                return this.__api.makeRequest('GET', detectPath, null, this.getHeaders(token));
+            });
+    }
+
+    // -------------------------------------------------------------------------
+    // Internal resolve + request helper
+    // -------------------------------------------------------------------------
+
+    /**
+     * Resolve the mount version for a path, rewrite the path, make the request,
+     * and return a { apiPath, body, version, mount } object.
+     *
+     * When the resolver is disabled (autoDetect:false, no matching engine), it
+     * preserves the caller's literal path byte-for-byte, keeping behaviour
+     * identical to the pre-KV-v2 client.
+     *
+     * @private
+     */
+    __resolveAndRequest(op, method, path, data) {
+        return this.__auth.getAuthToken()
+            .then((token) => {
+                const headers = this.getHeaders(token);
+
+                return this.__resolver.resolve(path)
+                    .then((resolved) => {
+                        const mount = resolved.mount;
+                        const version = resolved.version;
+                        let apiPath;
+                        let requestData = data;
+
+                        if (version === 2) {
+                            // Split the path into mount + logical sub-path and rewrite for KV v2
+                            const logicalPath = this.__logicalPath(path, mount);
+                            apiPath = rewritePath(version, op, mount, logicalPath);
+                            // Wrap data in { data: ... } on v2 writes
+                            if (op === 'write' && data !== null && data !== undefined) {
+                                requestData = { data };
+                            }
+                        } else {
+                            // v1 / disabled: preserve the caller's literal path byte-for-byte,
+                            // including any trailing slash, to maintain the old wire behaviour.
+                            apiPath = path;
+                        }
+
+                        return this.__api.makeRequest(method, apiPath, requestData, headers)
+                            .then((body) => ({ body, version, mount, apiPath }));
+                    });
+            });
+    }
+
+    /**
+     * Extract the logical path after the mount prefix.
+     * e.g. path='secret/foo/bar', mount='secret' => 'foo/bar'
+     * @private
+     */
+    __logicalPath(path, mount) {
+        const prefix = mount.replace(/\/+$/, '');
+        if (path === prefix) return '';
+        if (path.startsWith(prefix + '/')) return path.slice(prefix.length + 1);
+        return path;
+    }
+
     /**
      * Read secret from Vault
      * @param {string} path - path to the secret
@@ -180,11 +284,11 @@ class VaultClient {
      */
     read(path) {
         this.__log.debug('read secret %s', path);
-        return this.__auth.getAuthToken()
-            .then(token => this.__api.makeRequest('GET', path, null, this.getHeaders(token)))
-            .then(res => {
+        return this.__resolveAndRequest('read', 'GET', path, null)
+            .then(({ body, version }) => {
                 this.__log.debug('receive secret %s', path);
-                return Lease.fromResponse(res);
+                const normalised = normalizeResponse(version, 'read', body);
+                return Lease.fromResponse(normalised);
             })
             .catch((reason) => {
                 this.__log.error('read secret failed: %s', reason.message);
@@ -200,11 +304,11 @@ class VaultClient {
      */
     list(path) {
         this.__log.debug('list secrets %s', path);
-        return this.__auth.getAuthToken()
-            .then(token => this.__api.makeRequest('LIST', path, null, this.getHeaders(token)))
-            .then(res => {
+        return this.__resolveAndRequest('list', 'LIST', path, null)
+            .then(({ body, version }) => {
                 this.__log.debug('got secrets list %s', path);
-                return Lease.fromResponse(res);
+                const normalised = normalizeResponse(version, 'list', body);
+                return Lease.fromResponse(normalised);
             })
             .catch((reason) => {
                 this.__log.error('list secrets failed: %s', reason.message);
@@ -221,11 +325,10 @@ class VaultClient {
      */
     write(path, data) {
         this.__log.debug('write secret %s', path);
-        return this.__auth.getAuthToken()
-            .then((token) => this.__api.makeRequest('POST', path, data, this.getHeaders(token)))
-            .then((response) => {
+        return this.__resolveAndRequest('write', 'POST', path, data)
+            .then(({ body }) => {
                 this.__log.debug('secret %s was written', path);
-                return response;
+                return body;
             })
             .catch((reason) => {
                 this.__log.error('write secret failed: %s', reason.message);

package/src/kvTransform.js

@@ -0,0 +1,90 @@
+'use strict';
+
+/**
+ * Pure KV path-rewriting and response-normalizing helpers.
+ * No I/O; fully testable in isolation.
+ *
+ * rewritePath(version, op, mount, logicalPath) -> apiPath
+ * normalizeResponse(version, op, body)         -> normalized body
+ */
+
+// Map of op -> v2 path segment inserted between mount and logical path.
+const V2_SEGMENT = {
+    read:            'data',
+    write:           'data',
+    delete:          'data',
+    update:          'data',
+    list:            'metadata',
+    readMetadata:    'metadata',
+    deleteMetadata:  'metadata',
+    deleteVersions:  'delete',
+    undeleteVersions:'undelete',
+    destroyVersions: 'destroy',
+};
+
+/**
+ * Rewrite a logical path to the correct API path for the given engine version.
+ *
+ * @param {number} version   - Engine version (2 = KV v2; anything else = passthrough)
+ * @param {string} op        - Operation name (read, write, list, delete, update, …)
+ * @param {string} mount     - Mount point (e.g. "secret" or "secret/")
+ * @param {string} logicalPath - Path relative to the mount (e.g. "team/svc")
+ * @returns {string}
+ */
+function rewritePath(version, op, mount, logicalPath) {
+    // Normalise trailing slash on mount
+    const m = mount.replace(/\/+$/, '');
+
+    if (version !== 2) {
+        // v1 / non-kv: simple concatenation
+        return logicalPath ? `${m}/${logicalPath}` : m;
+    }
+
+    const segment = V2_SEGMENT[op] || 'data';
+    return `${m}/${segment}/${logicalPath}`;
+}
+
+/**
+ * Normalise a Vault API response body for the given engine version and operation.
+ *
+ * For v1 / non-kv the body is always returned as-is.
+ * For v2:
+ *  - read:         body.data is replaced with body.data.data; body.metadata is set to body.data.metadata
+ *  - readMetadata: body.data is replaced with the original body.data (unwrapped one level)
+ *  - write/delete/update/…: body returned as-is
+ *
+ * @param {number} version
+ * @param {string} op
+ * @param {*}      body
+ * @returns {*}
+ */
+function normalizeResponse(version, op, body) {
+    if (version !== 2) {
+        return body;
+    }
+
+    if (op === 'read') {
+        if (!body || !body.data) {
+            return body;
+        }
+        // Promote inner data/metadata to top-level response fields
+        const result = Object.assign({}, body);
+        result.metadata = body.data.metadata;
+        result.data = body.data.data;
+        return result;
+    }
+
+    if (op === 'readMetadata') {
+        if (!body || !body.data) {
+            return body;
+        }
+        const result = Object.assign({}, body);
+        result.data = body.data;
+        return result;
+    }
+
+    // All other v2 ops (write, list, delete, update, deleteVersions, …): passthrough
+    return body;
+}
+
+module.exports = { rewritePath, normalizeResponse };