node-vault-client 2.0.0 → 2.1.0

package/src/VaultClient.js

@@ -1,6 +1,5 @@
 'use strict';
 
-const _ = require('lodash');
 const Lease = require('./Lease');
 const errors = require('./errors');
 const VaultApiClient = require('./VaultApiClient');
@@ -9,6 +8,10 @@ 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 noop = () => {};
 const vaultInstances = {};
 
 class VaultClient {
@@ -23,6 +26,12 @@ class VaultClient {
      * @param {Object} [options.api.requestOptions] - extra options merged into every HTTP
      *      request (e.g. an undici `dispatcher` for a proxy/SOCKS agent or custom TLS/CA trust).
      *      See {@link VaultApiClient#constructor}.
+     * @param {Object} [options.api.kv] - KV engine options
+     * @param {boolean} [options.api.kv.autoDetect=false] - When true, auto-detect KV version per mount
+     * @param {Object} [options.api.engines] - Mount-to-version overrides, e.g. { secret: 2, legacy: 1 }
+     * @param {String} [options.api.namespace] - Vault namespace applied (as `X-Vault-Namespace`) to
+     *      every request across all auth backends. For backward compatibility `options.auth.config.namespace`
+     *      is also honored when this is not set.
      * @param {Object} options.auth
      * @param {String} options.auth.type
      * @param {Object} options.auth.config - auth configuration variables
@@ -31,9 +40,18 @@ class VaultClient {
     constructor(options) {
         this.__log = this.__setupLogger(options.logger);
 
+        // Namespace is a server-routing concern that applies to every request, so it is resolved
+        // once here and owned by the API client (see VaultApiClient#makeRequest) rather than being
+        // reapplied in each auth backend. `api.namespace` is the canonical location; the legacy
+        // `auth.config.namespace` is still honored for backward compatibility.
+        const namespace = (options.api && options.api.namespace !== undefined)
+            ? options.api.namespace
+            : (options.auth && options.auth.config ? options.auth.config.namespace : undefined);
+
         this.__api = new VaultApiClient(
             options.api,
-            this.__log
+            this.__log,
+            namespace
         );
 
         /**
@@ -45,7 +63,24 @@ class VaultClient {
             this.__api
         );
 
-        this.__namespace = options.auth.config.namespace;
+        // KV v2 support
+        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,
+        });
     }
 
     /**
@@ -188,16 +223,121 @@ class VaultClient {
     }
 
     getHeaders(token) {
-        if (this.__namespace) {
-            return {
-                'X-Vault-Token': token.getId(),
-                'X-Vault-Namespace': this.__namespace
-            }
-        }
-
+        // Namespace is injected centrally by VaultApiClient#makeRequest, so callers only
+        // need to supply the token here.
         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 pipeline — the single entry point
+    // -------------------------------------------------------------------------
+
+    /**
+     * The unified request pipeline: fetch an auth token, build headers, resolve
+     * the mount version, rewrite the path for the engine version, make the
+     * request, and return a { body, version, mount, apiPath } object.
+     *
+     * When the resolver is disabled (autoDetect:false, no engines), resolution
+     * yields a v1 passthrough, preserving identical behavior to before.
+     *
+     * @param {string} op - logical operation (read, write, list, delete, update, deleteVersions, …)
+     * @param {string} method - HTTP method
+     * @param {string} path - caller-supplied secret path
+     * @param {Object|null} data - request body
+     * @param {Object} [extraHeaders] - extra HTTP headers merged over the token header
+     * @param {Object} [options]
+     * @param {boolean} [options.raw=false] - skip mount resolution and path rewriting;
+     *      the literal path and data are sent as-is (raw request() semantics)
+     * @param {boolean} [options.v2Only=false] - reject with UnsupportedOperationError
+     *      unless the resolved mount is a KV v2 engine
+     * @param {boolean} [options.wrapData=false] - force the { data } envelope on every
+     *      engine version (merge-patch update() semantics); by default only v2
+     *      write/update wrap non-null data and everything else passes through
+     * @returns {Promise<{body: *, version: (number|undefined), mount: (string|undefined), apiPath: string}>}
+     * @private
+     */
+    __resolveAndRequest(op, method, path, data, extraHeaders, options) {
+        const { raw = false, v2Only = false, wrapData = false } = options || {};
+
+        return this.__auth.getAuthToken()
+            .then((token) => {
+                const headers = Object.assign({}, this.getHeaders(token), extraHeaders || {});
+
+                if (raw) {
+                    return this.__api.makeRequest(method, path, data, headers)
+                        .then((body) => ({ body, version: undefined, mount: undefined, apiPath: path }));
+                }
+
+                return this.__resolver.resolve(path)
+                    .then(({ mount, version }) => {
+                        if (v2Only && version !== 2) {
+                            throw new errors.UnsupportedOperationError(
+                                `Operation "${op}" is only supported on KV v2 mounts. ` +
+                                `Mount "${mount}" is not a KV v2 engine.`
+                            );
+                        }
+
+                        let apiPath;
+                        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);
+                        } else {
+                            // v1 / disabled: preserve the caller's literal path byte-for-byte,
+                            // including any trailing slash, to maintain the old wire behavior.
+                            apiPath = path;
+                        }
+
+                        // Data envelope: wrapData forces { data } on every engine version
+                        // (merge-patch update() semantics — v1 mounts reject PATCH anyway);
+                        // otherwise only v2 write/update wrap non-null data.
+                        let requestData = data;
+                        if (wrapData) {
+                            requestData = { data };
+                        } else if (version === 2 && (op === 'write' || op === 'update')
+                                && data !== null && data !== undefined) {
+                            requestData = { data };
+                        }
+
+                        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;
+    }
+
+    // -------------------------------------------------------------------------
+    // Public API — existing methods (with KV v2 awareness)
+    // -------------------------------------------------------------------------
+
     /**
      * Read secret from Vault
      * @param {string} path - path to the secret
@@ -205,11 +345,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);
@@ -225,11 +365,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);
@@ -246,11 +386,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);
@@ -258,19 +397,185 @@ class VaultClient {
             });
     }
 
+    /**
+     * Delete (soft-delete latest version) a secret.
+     *
+     * On KV v1 / non-kv mounts this sends DELETE to the raw path.
+     * On KV v2 mounts this sends DELETE to the data/ path, soft-deleting the latest version.
+     *
+     * @param {string} path
+     * @returns {Promise<Object>}
+     */
+    delete(path) {
+        this.__log.debug('delete secret %s', path);
+        return this.__resolveAndRequest('delete', 'DELETE', path, null)
+            .then(({ body }) => {
+                this.__log.debug('secret %s was deleted', path);
+                return body;
+            })
+            .catch((reason) => {
+                this.__log.error('delete secret failed: %s', reason.message);
+                throw reason;
+            });
+    }
+
+    // -------------------------------------------------------------------------
+    // New methods
+    // -------------------------------------------------------------------------
+
+    /**
+     * PATCH (update) a KV v2 secret using merge-patch semantics.
+     * Sends the data wrapped in { data: ... } with Content-Type: application/merge-patch+json.
+     *
+     * @param {string} path
+     * @param {object} data
+     * @returns {Promise<Object>}
+     */
+    update(path, data) {
+        this.__log.debug('update (patch) secret %s', path);
+        // wrapData: update() is a KV v2 merge-patch operation, so the { data } envelope
+        // is always applied (v1 mounts do not support PATCH and Vault will return 405)
+        return this.__resolveAndRequest('update', 'PATCH', path, data,
+            { 'Content-Type': 'application/merge-patch+json' }, { wrapData: true })
+            .then(({ body }) => body)
+            .catch((reason) => {
+                this.__log.error('update secret failed: %s', reason.message);
+                throw reason;
+            });
+    }
+
+    /**
+     * Raw request — literal path, no path rewriting or response unwrapping.
+     * Returns the parsed body directly.
+     *
+     * @param {string} method - HTTP method
+     * @param {string} path   - literal API path
+     * @param {object} [data] - request body
+     * @returns {Promise<Object>}
+     */
+    request(method, path, data) {
+        this.__log.debug('raw request %s %s', method, path);
+        return this.__resolveAndRequest('request', method, path, data === undefined ? null : data, null, { raw: true })
+            .then(({ body }) => body)
+            .catch((reason) => {
+                this.__log.error('raw request failed: %s', reason.message);
+                throw reason;
+            });
+    }
+
+    // -------------------------------------------------------------------------
+    // KV v2-only helpers
+    // -------------------------------------------------------------------------
+
+    /**
+     * Soft-delete specific versions of a KV v2 secret.
+     * Throws UnsupportedOperationError on non-v2 mounts.
+     *
+     * @param {string} path
+     * @param {number[]} versions
+     * @returns {Promise<Object>}
+     */
+    deleteVersions(path, versions) {
+        this.__log.debug('deleteVersions %s %j', path, versions);
+        return this.__v2Only('deleteVersions', 'POST', path, { versions })
+            .catch((reason) => {
+                this.__log.error('deleteVersions failed: %s', reason.message);
+                throw reason;
+            });
+    }
+
+    /**
+     * Undelete (restore) specific versions of a KV v2 secret.
+     * Throws UnsupportedOperationError on non-v2 mounts.
+     *
+     * @param {string} path
+     * @param {number[]} versions
+     * @returns {Promise<Object>}
+     */
+    undeleteVersions(path, versions) {
+        this.__log.debug('undeleteVersions %s %j', path, versions);
+        return this.__v2Only('undeleteVersions', 'POST', path, { versions })
+            .catch((reason) => {
+                this.__log.error('undeleteVersions failed: %s', reason.message);
+                throw reason;
+            });
+    }
+
+    /**
+     * Permanently destroy specific versions of a KV v2 secret.
+     * Throws UnsupportedOperationError on non-v2 mounts.
+     *
+     * @param {string} path
+     * @param {number[]} versions
+     * @returns {Promise<Object>}
+     */
+    destroyVersions(path, versions) {
+        this.__log.debug('destroyVersions %s %j', path, versions);
+        return this.__v2Only('destroyVersions', 'POST', path, { versions })
+            .catch((reason) => {
+                this.__log.error('destroyVersions failed: %s', reason.message);
+                throw reason;
+            });
+    }
+
+    /**
+     * Read KV v2 metadata for a secret.
+     * Throws UnsupportedOperationError on non-v2 mounts.
+     *
+     * @param {string} path
+     * @returns {Promise<Object>}
+     */
+    readMetadata(path) {
+        this.__log.debug('readMetadata %s', path);
+        return this.__v2Only('readMetadata', 'GET', path, null)
+            .then((body) => {
+                return normalizeResponse(2, 'readMetadata', body);
+            })
+            .catch((reason) => {
+                this.__log.error('readMetadata failed: %s', reason.message);
+                throw reason;
+            });
+    }
+
+    /**
+     * Delete all metadata and version history for a KV v2 secret (permanent).
+     * Throws UnsupportedOperationError on non-v2 mounts.
+     *
+     * @param {string} path
+     * @returns {Promise<Object>}
+     */
+    deleteMetadata(path) {
+        this.__log.debug('deleteMetadata %s', path);
+        return this.__v2Only('deleteMetadata', 'DELETE', path, null)
+            .catch((reason) => {
+                this.__log.error('deleteMetadata failed: %s', reason.message);
+                throw reason;
+            });
+    }
+
+    /**
+     * Shared implementation for v2-only operations: delegates to the unified
+     * pipeline with the KV v2 version assertion enabled.
+     * @private
+     */
+    __v2Only(op, method, path, data) {
+        return this.__resolveAndRequest(op, method, path, data, null, { v2Only: true })
+            .then(({ body }) => body);
+    }
+
     /**
      * @private
      */
     __setupLogger(logger) {
         if (logger === false) {
             return {
-                error: _.noop,
-                warn: _.noop,
-                info: _.noop,
-                debug: _.noop,
-                trace: _.noop,
+                error: noop,
+                warn: noop,
+                info: noop,
+                debug: noop,
+                trace: noop,
             }
-        } else if (_.intersection(_.functionsIn(logger), ['error', 'warn', 'info', 'debug', 'trace']).length >= 5) {
+        } else if (['error', 'warn', 'info', 'debug', 'trace'].every((method) => typeof logger?.[method] === 'function')) {
             return logger
         } else {
             return {
@@ -279,7 +584,7 @@ class VaultClient {
                 info: console.info,
                 trace: console.trace,
                 // avoid output sensitive information
-                debug: _.noop
+                debug: noop
             };
         }
     }

package/src/VaultNodeConfig.js

@@ -1,12 +1,52 @@
 'use strict';
 
 const path = require('path');
-const Bluebird = require('bluebird');
-const _ = require('lodash');
-const assignDeep = require('assign-deep');
 
 const errors = require('./errors');
 
+function isObject(value) {
+    return value !== null && typeof value === 'object';
+}
+
+function isPlainObject(value) {
+    if (!isObject(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === null || proto === Object.prototype;
+}
+
+/**
+ * Recursively merges own enumerable properties of `source` into `target`,
+ * mutating and returning `target`. Nested objects and arrays are merged in
+ * place, other values overwrite, and `undefined` source values are skipped.
+ * Prototype-polluting keys (`__proto__`, `constructor`, `prototype`) are
+ * skipped. Covers the subset of `lodash.merge` behavior this client relies on.
+ */
+function deepMerge(target, source) {
+    for (const key of Object.keys(source)) {
+        if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+            continue;
+        }
+
+        const sourceValue = source[key];
+        if (sourceValue === undefined) {
+            continue;
+        }
+
+        const targetValue = target[key];
+        if (isObject(sourceValue) && isObject(targetValue)) {
+            deepMerge(targetValue, sourceValue);
+        } else if (isObject(sourceValue)) {
+            target[key] = structuredClone(sourceValue);
+        } else {
+            target[key] = sourceValue;
+        }
+    }
+
+    return target;
+}
+
 class VaultNodeConfig {
 
     constructor(vault) {
@@ -29,45 +69,55 @@ class VaultNodeConfig {
         let requiredData = {};
 
         this.__traverse(substitutionMap, (key, val) => {
-            const splitRes = val.split('#');
-            const path = splitRes[0], value = splitRes[1];
-            if (path === undefined || value === undefined) {
-                throw new errors.InvalidArgumentsError('Invalid format of substitution value');
-            }
-
-            requiredData[path] = null;
+            const { vaultPath } = this.__parseSubstitutionValue(val);
+            requiredData[vaultPath] = null;
         });
 
-        let promises = _.mapValues(requiredData, (value, path) => this.__vault.read(path));
+        const vaultPaths = Object.keys(requiredData);
 
-        return Bluebird.props(promises).then(results => {
-            requiredData = _.mapValues(requiredData, (value, path) => results[path].getData());
+        return Promise.all(vaultPaths.map((vaultPath) => this.__vault.read(vaultPath))).then((leases) => {
+            requiredData = Object.fromEntries(
+                vaultPaths.map((vaultPath, index) => [vaultPath, leases[index].getData()])
+            );
 
             this.__traverse(substitutionMap, (key, val, obj) => {
-                const splitRes = val.split('#');
-                const path = splitRes[0], value = splitRes[1];
-                const res = requiredData[path][value];
+                const { vaultPath, value } = this.__parseSubstitutionValue(val);
+                const res = requiredData[vaultPath][value];
                 if (res === undefined) {
                     throw new errors.VaultError(`Can't find substitution for "${val}"`);
                 }
 
-                obj[key] = requiredData[path][value];
+                obj[key] = requiredData[vaultPath][value];
             });
 
-            return assignDeep(this.__nodeConfig, substitutionMap);
+            return deepMerge(this.__nodeConfig, substitutionMap);
         });
     }
 
+    /**
+     * Splits a substitution value of the form "<vaultPath>#<value>".
+     *
+     * @private
+     */
+    __parseSubstitutionValue(val) {
+        const [vaultPath, value] = val.split('#');
+        if (!vaultPath || !value) {
+            throw new errors.InvalidArgumentsError('Invalid format of substitution value');
+        }
+
+        return { vaultPath, value };
+    }
+
     /**
      * @private
      */
     __getSubstitutionMap() {
-        let config_dir = this.__nodeConfig.util.initParam('NODE_CONFIG_DIR', path.join( process.cwd(), 'config') );
-        if (config_dir.indexOf('.') === 0) {
-            config_dir = path.join(process.cwd() , config_dir);
+        let configDir = this.__nodeConfig.util.initParam('NODE_CONFIG_DIR', path.join(process.cwd(), 'config'));
+        if (configDir.indexOf('.') === 0) {
+            configDir = path.join(process.cwd(), configDir);
         }
 
-        const fullFilename = path.join(config_dir, 'custom-vault-variables.js');
+        const fullFilename = path.join(configDir, 'custom-vault-variables.js');
 
         let fileContent;
         try {
@@ -76,20 +126,16 @@ class VaultNodeConfig {
             throw new errors.VaultError('Config file ' + fullFilename + ' cannot be read');
         }
 
-        if (!_.isPlainObject(fileContent)) {
+        if (!isPlainObject(fileContent)) {
             throw new errors.VaultError('Config file ' + fullFilename + ' should return plain object');
         }
 
-        return _.cloneDeep(fileContent);
+        return structuredClone(fileContent);
     }
 
     __traverse(o, func) {
-        for (let i in o) {
-            if (!Object.hasOwn(o, i)) {
-                continue;
-            }
-
-            if (o[i] !== null && typeof(o[i]) === "object") {
+        for (const i of Object.keys(o)) {
+            if (o[i] !== null && typeof o[i] === 'object') {
                 //going one step down in the object tree!!
                 this.__traverse(o[i], func);
             } else if (typeof o[i] === 'string') {
@@ -102,3 +148,6 @@ class VaultNodeConfig {
 }
 
 module.exports = VaultNodeConfig;
+// The prototype-pollution guard in deepMerge is a deliberate security control;
+// the helper is exported so tests can exercise it directly.
+module.exports.deepMerge = deepMerge;

package/src/auth/VaultAppRoleAuth.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const VaultBaseAuth = require('./VaultBaseAuth');
+const errors = require('../errors');
 
 class VaultAppRoleAuth extends VaultBaseAuth {
 
@@ -10,15 +11,19 @@ class VaultAppRoleAuth extends VaultBaseAuth {
      * @param {Object} config
      * @param {String} config.role_id - RoleID of the AppRole.
      * @param {String} [config.secret_id] - required when bind_secret_id is enabled SecretID belonging to AppRole.
-     * @param {String} [config.namespace] - Optional. Vault namespace, sent as the X-Vault-Namespace header.
+     * @param {String} [config.namespace] - Optional. Vault namespace. Applied as the X-Vault-Namespace
+     *   header to every request by {@link VaultApiClient}; see {@link VaultClient#constructor}.
      * @param {String} mount - Vault's  mount point ("approle" by default)
      */
     constructor(apiClient, logger, config, mount) {
         super(apiClient, logger, mount || 'approle');
 
+        if (!config || !config.role_id) {
+            throw new errors.InvalidArgumentsError('"role_id" should be provided for VaultAppRoleAuth');
+        }
+
         this.__roleId = config.role_id;
         this.__secretId = config.secret_id;
-        this.__namespace = config.namespace;
     }
 
     _authenticate() {
@@ -27,18 +32,13 @@ class VaultAppRoleAuth extends VaultBaseAuth {
             this.__roleId
         );
 
-        const headers = {};
-        if (this.__namespace) {
-            headers['X-Vault-Namespace'] = this.__namespace;
-        }
-
         return this.__apiClient.makeRequest('POST', `/auth/${this._mount}/login`, {
             role_id: this.__roleId,
             secret_id: this.__secretId,
-        }, headers).then(res => {
+        }).then(res => {
             this._log.debug(
-                'receive token: %s',
-                res.auth.client_token
+                'received token (accessor=%s)',
+                res.auth.accessor
             );
             return this._getTokenEntity(res.auth.client_token);
         });