node-vault-client 1.0.2 → 1.0.4

package/README.md

@@ -29,6 +29,153 @@ 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.
+- A detection answer without a string `path` and `type` fails the call and is not cached, and an
+  answer whose mount does not contain the requested path is rejected for that caller only. Auth
+  mounts are cached as `auth/<mount>`, so they never collide with a secrets mount of the same name.
+
+## Path validation
+
+Since 1.0.4, `read`, `list` and `write` reject a path with `InvalidArgumentsError`, before any
+request is sent (including the login and mount detection), when Vault or the HTTP stack would
+resolve it to a different path than the one passed (GHSA-rr65-m54w-rfr9, GHSA-wf8v-q2h3-hgjm):
+
+- an empty path, or one that is not a string;
+- `?`, `#`, `\`, a control character (U+0000–U+001F, U+007F), an unpaired surrogate or a
+  trailing space;
+- a percent-encoded `.`, `/`, `\` or `%` (`%2e`, `%2f`, `%5c`, `%25`, in any case);
+- an empty segment such as `a//b`, which the client used to collapse into `a/b` before sending, so
+  `tenants/${id}/key` with an empty `id` addressed `tenants/key`;
+- a `.` or `..` segment, which Vault redirects to the cleaned path and the client followed with its
+  token;
+- a percent-encoded mount (`secre%74/foo`, or `team/k%76/foo` for the mount `team/kv`).
+
+Leading slashes are dropped before the mount is resolved, so `/secret/foo` and `secret/foo`
+address the same key. One trailing slash is kept, as in `list('secret/apps/')`. A key name that
+needs `?` or `#` can still be addressed percent-encoded (`%3F`, `%23`).
+
+These checks stop a path from reaching a different Vault path than the one it names; they do not
+stop a caller from naming another tenant's key, so keep validating lower-trust input that goes
+into a path. A validation error's message says which rule failed but not the path.
+
+## Logging
+
+The default logger writes `error`, `warn`, `info` and `trace` to `console` and discards `debug`. A
+custom logger must implement all five methods; one missing any of them is silently replaced by the
+default logger. Since 1.0.4 no log line, at any level, carries a Vault token, the AppRole
+`role_id`/`secret_id`, the Kubernetes JWT or a Vault response body: request logs name the method
+and URL, auth logs name the token accessor, and failure logs keep only the HTTP status and Vault's
+`errors` strings. Errors the client throws still carry the request in `err.options` (including the
+`X-Vault-Token` header) and the response in `err.response`, but these are no longer printed when
+the error is logged or serialised; the `StatusCodeError` message is still `"<status> - <body>"`, so
+log `err.statusCode` and `err.error.errors` rather than the message if the body may hold secrets.
+
 ## Supported Auth Backends
 
 * [AWS IAM](https://www.vaultproject.io/docs/auth/aws.html#iam-auth-method)
@@ -65,10 +212,13 @@ 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 |
-| 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.logger] | <code>Object</code> \| <code>false</code> |  | Logger that implements all five of "error", "warn", "info", "debug" and "trace"; one missing any of them is silently replaced by the default logger. The default logger writes to `console`, except `debug`, which is discarded. Pass `false` to disable logging. See [Logging](#logging). |
 
 #### vaultClient.fillNodeConfig()
 Populates Vault's values to NPM "config" module

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-vault-client",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "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,240 @@
+'use strict';
+
+const { VaultError, InvalidArgumentsError } = require('./errors');
+const safeMessage = require('./safeMessage');
+const { trimTrailingSlashes, trimSlashes } = require('./slashes');
+
+/** True when `mount` is `path` itself or a whole-segment prefix of it. */
+function containsPath(mount, path) {
+    return mount !== '' && (path === mount || path.startsWith(mount + '/'));
+}
+
+/**
+ * Per GHSA-rr65/GHSA-wf8v a mount must be named literally: Vault decodes the path, so
+ * 'team/k%76/x' would reach the 'team/kv' mount while matching it neither in the engines map
+ * nor as a prefix, and the KV v2 rewrite would be skipped or built on the wrong mount.
+ */
+function encodedMountError(mount) {
+    return new InvalidArgumentsError(
+        `Invalid secret path: it does not start with the mount "${mount}" it resolved to; ` +
+        'do not percent-encode the mount'
+    );
+}
+
+// '%2f' and '%25' never get here (VaultClient rejects them), so one decode is what Vault sees.
+function decodePath(path) {
+    try {
+        return decodeURIComponent(path);
+    } catch (e) {
+        return path;
+    }
+}
+
+/**
+ * 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)
+ * @param {string}   [opts.namespace]  - the client's Vault namespace (X-Vault-Namespace)
+ */
+class MountResolver {
+    constructor(detectFn, enginesOverride, logger, opts) {
+        this.__detectFn = detectFn;
+        // Leading slashes go too: VaultClient drops them from the path before it gets here.
+        this.__engines = Object.entries(enginesOverride || {})
+            .sort((a, b) => b[0].length - a[0].length)
+            .map(([prefix, version]) => [trimSlashes(prefix), Number(version)]);
+        this.__log = logger;
+        this.__disabled = opts && opts.disabled === true;
+        // Vault reports a mount in a child namespace with its full namespace path
+        // ("ns1/ns2/secret/"), while the caller's path is relative to this namespace.
+        const namespace = opts && typeof opts.namespace === 'string' ? trimSlashes(opts.namespace) : '';
+        this.__namespacePrefix = namespace ? `${namespace}/` : '';
+
+        // 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);
+        const decodedOverride = this.__enginesOverrideLookup(decodePath(path));
+        if (decodedOverride !== null && (override === null || override.mount !== decodedOverride.mount)) {
+            return Promise.reject(encodedMountError(decodedOverride.mount));
+        }
+        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.
+        //    Each caller checks the result against its own path, so one caller's bad path
+        //    cannot fail others sharing the detection.
+        const interimKey = path.split('/')[0];
+        return this.__detectWithCache(interimKey, path).then((entry) => {
+            if (!containsPath(entry.mount, path)) {
+                throw encodedMountError(entry.mount);
+            }
+            return entry;
+        });
+    }
+
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+
+    /**
+     * Longest-prefix match against the engines override map.
+     * Returns { mount, version } or null if no match found.
+     */
+    __enginesOverrideLookup(path) {
+        for (const [prefix, version] of this.__engines) {
+            if (containsPath(prefix, path)) {
+                return { mount: prefix, 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 (containsPath(mountKey, path)) {
+                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 (containsPath(entry.mount, path)) {
+                    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');
+                }
+
+                // Require a mounts-endpoint shape (string path and type) and never fall back
+                // to a caller-derived key or a default type (GHSA-wf8v-q2h3-hgjm). This does not
+                // authenticate the response: a planted secret could carry the same fields. What
+                // keeps the detection request on the mounts endpoint is the path validation in
+                // VaultClient; this only stops a malformed answer from becoming routing.
+                if (typeof info.path !== 'string' || typeof info.type !== 'string' || !trimTrailingSlashes(info.path)) {
+                    throw new Error('Unexpected detection response shape (missing string path/type)');
+                }
+                const canonicalMount = this.__canonicalMount(info.path, path);
+                const type = info.type;
+                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);
+
+                // Cache only an answer that contains the path it was asked for; resolve()
+                // rejects a caller whose path the mount does not contain.
+                if (containsPath(canonicalMount, path)) {
+                    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);
+                // safeMessage: this message is logged by the operation's catch handler, so it
+                // must not embed a raw response body (GHSA-2vr8-g4vw-7xpm).
+                throw new VaultError(
+                    `Failed to detect KV engine version for mount "${interimKey}" (path: ${path}): ${safeMessage(err)}. ` +
+                    'Set api.engines or disable autoDetect to bypass detection.'
+                );
+            });
+
+        this.__inflight.set(interimKey, promise);
+        return promise;
+    }
+
+    /**
+     * The cache key for a detected mount. For auth mounts Vault reports the path without the
+     * reserved "auth/" prefix (auth/apps/role/r -> "apps/"), so it is re-added and the entry
+     * cannot collide with a secrets mount of the same name. A mount in a child namespace is
+     * reported with the client's namespace in front; that prefix is dropped when only the
+     * shorter form contains the path.
+     */
+    __canonicalMount(reportedPath, path) {
+        const withTable = (mount) => (path.startsWith('auth/') ? `auth/${mount}` : mount);
+        const reported = trimTrailingSlashes(reportedPath);
+        const mount = withTable(reported);
+        if (!containsPath(mount, path) && this.__namespacePrefix && reported.startsWith(this.__namespacePrefix)) {
+            const relative = withTable(reported.slice(this.__namespacePrefix.length));
+            if (containsPath(relative, path)) {
+                return relative;
+            }
+        }
+        return mount;
+    }
+
+    /**
+     * Simple first-segment extraction used only for the disabled path.
+     */
+    __extractMount(path) {
+        return path.split('/')[0];
+    }
+}
+
+module.exports = MountResolver;

package/src/VaultApiClient.js

@@ -4,6 +4,27 @@ const rp = require('request-promise');
 const urljoin = require('url-join');
 const _ = require('lodash');
 
+/**
+ * request-promise errors keep the request `options` (the `X-Vault-Token` header and the request
+ * body: written secrets, AppRole credentials, the Kubernetes JWT) and the `response`, whose
+ * request carries the same headers. Printing such an error (console.error(err), an error tracker,
+ * JSON.stringify) printed the token. Keep both properties readable, but non-enumerable, so they
+ * no longer show up when the error is inspected or serialised.
+ *
+ * @param {*} err
+ * @returns {*} the same error
+ */
+function hideRequestDetails(err) {
+    if (err && typeof err === 'object') {
+        ['options', 'response'].forEach((key) => {
+            if (Object.prototype.hasOwnProperty.call(err, key)) {
+                Object.defineProperty(err, key, { enumerable: false });
+            }
+        });
+    }
+    return err;
+}
+
 class VaultApiClient {
 
     /**
@@ -42,12 +63,15 @@ class VaultApiClient {
 
         return rp(requestOptions)
             .then((response) => {
-                this._logger.debug('%s %s response body:\n%s',
+                // Do not log the response body: Vault responses carry secret material (auth
+                // tokens, secret reads). See issue #204.
+                this._logger.debug('%s %s -> response received',
                     requestOptions.method,
-                    requestOptions.uri,
-                    JSON.stringify(response, null, ' ')
+                    requestOptions.uri
                 );
                 return response;
+            }, (err) => {
+                throw hideRequestDetails(err);
             });
     }
 }

package/src/VaultClient.js

@@ -9,8 +9,72 @@ 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 safeMessage = require('./safeMessage');
+const { trimTrailingSlashes } = require('./slashes');
 const vaultInstances = {};
 
+// The URL parser and Vault reinterpret these: '?' starts the query, '#' the fragment, '\' is a
+// path separator for http(s), and tab/LF/CR and trailing C0 controls or spaces are dropped. Any
+// of them lets a KV path address a different key.
+// eslint-disable-next-line no-control-regex
+const UNSAFE_KV_PATH_CHARS = /[?#\\\u0000-\u001f\u007f]/;
+// An unpaired surrogate (String.prototype.isWellFormed() needs Node 20; this line supports 14+).
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?:^|[^\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+
+/**
+ * Rejects a KV method path that the URL parser or Vault would resolve to a path other than
+ * `<mount>/<kv segment>/<logical path>` (GHSA-rr65-m54w-rfr9, GHSA-wf8v-q2h3-hgjm).
+ *
+ * Vault removes '.' and '..' segments and redirects, which `request` follows with the token, and
+ * url-join collapses an empty segment ('tenants//key' becomes 'tenants/key') before the request
+ * is sent. Encoded forms are rejected rather than decoded: Vault decodes %2e and %2f before it
+ * resolves '..', and Vault 2.x decodes again on every redirect hop, so a %25-encoded escape
+ * becomes %2e or %2f on the first hop and a real dot segment or separator on the second. No other
+ * escape can form a dot segment or a separator, so the segments are then checked as written.
+ *
+ * The messages never include the path: the KV methods log them at error level, and the path
+ * may be built from user data that was never logged before.
+ *
+ * The mount (first segment) must not be percent-encoded: the engines override and mount
+ * detection match the path as written, but Vault decodes it.
+ *
+ * @param {*} path - caller-supplied secret path
+ * @returns {string} the path without leading slashes; resolving the mount on it keeps the KV v2
+ *      rewrite from taking '/secret/foo' for a key in 'secret/'
+ * @throws {InvalidArgumentsError}
+ * @private
+ */
+function assertSafeKvPath(path) {
+    if (typeof path !== 'string' || path === '') {
+        throw new errors.InvalidArgumentsError('Invalid secret path: expected a non-empty string');
+    }
+    if (UNSAFE_KV_PATH_CHARS.test(path) || path.endsWith(' ') || LONE_SURROGATE.test(path)) {
+        throw new errors.InvalidArgumentsError(
+            'Invalid secret path: \'?\', \'#\', \'\\\', control characters, unpaired surrogates and a ' +
+            'trailing space are not allowed'
+        );
+    }
+    if (/%(2e|2f|5c|25)/i.test(path)) {
+        throw new errors.InvalidArgumentsError(
+            'Invalid secret path: encoded dots, separators or percent signs are not allowed'
+        );
+    }
+    const trimmed = path.replace(/^\/+/, '');
+    if (trimmed.split('/')[0].includes('%')) {
+        throw new errors.InvalidArgumentsError('Invalid secret path: the mount must not be percent-encoded');
+    }
+    // One trailing slash is allowed: list() addresses a folder with it.
+    const segments = trimmed.replace(/\/$/, '').split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw new errors.InvalidArgumentsError(
+            'Invalid secret path: empty, \'.\' and \'..\' segments are not allowed'
+        );
+    }
+    return trimmed;
+}
+
 class VaultClient {
 
     /**
@@ -20,10 +84,20 @@ 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
-     * @param {Object|false} options.logger - Logger that supports "error", "info", "warn", "trace", "debug" methods. Uses `console` by default. Pass `false` to disable logging.
+     * @param {Object|false} options.logger - Logger that implements all five of "error", "warn", "info", "debug"
+     *      and "trace"; one missing any of them is silently replaced by the default logger. The default logger
+     *      writes to `console`, except "debug", which is discarded. Pass `false` to disable logging.
      */
     constructor(options) {
         this.__log = this.__setupLogger(options.logger);
@@ -43,6 +117,26 @@ 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,
+            namespace: this.__namespace,
+        });
     }
 
     /**
@@ -173,6 +267,96 @@ 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) {
+        // KV paths are validated before the token fetch, mount resolution and the autoDetect
+        // detection request (GHSA-rr65-m54w-rfr9).
+        try {
+            path = assertSafeKvPath(path);
+        } catch (err) {
+            return Promise.reject(err);
+        }
+
+        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 = trimTrailingSlashes(mount);
+        if (path === prefix) return '';
+        if (path.startsWith(prefix + '/')) return path.slice(prefix.length + 1);
+        // Detection decodes the path, so with a multi-segment mount 'team/k%76/foo' resolves to
+        // 'team/kv'; rewriting it as a key inside that mount would address 'team/kv/team/kv/foo'
+        // (GHSA-rr65-m54w-rfr9). MountResolver.resolve() already rejects that; this guards the
+        // rewrite itself.
+        throw new errors.InvalidArgumentsError(
+            `Invalid secret path: it does not start with the mount "${prefix}" it resolved to; ` +
+            'do not percent-encode the mount'
+        );
+    }
+
     /**
      * Read secret from Vault
      * @param {string} path - path to the secret
@@ -180,14 +364,14 @@ 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);
+                this.__log.error('read secret failed: %s', safeMessage(reason));
                 throw reason;
             });
     }
@@ -200,14 +384,14 @@ 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);
+                this.__log.error('list secrets failed: %s', safeMessage(reason));
                 throw reason;
             });
     }
@@ -221,14 +405,13 @@ 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);
+                this.__log.error('write secret failed: %s', safeMessage(reason));
                 throw reason;
             });
     }

package/src/auth/VaultAppRoleAuth.js

@@ -20,9 +20,11 @@ class VaultAppRoleAuth extends VaultBaseAuth {
     }
 
     _authenticate() {
+        // Never log the role_id: for a role with bind_secret_id=false it is the whole login
+        // credential (GHSA-x5xf-r8x2-647h).
         this._log.info(
-            'making authentication request: role_id=%s',
-            this.__roleId
+            'making authentication request: approle mount=%s',
+            this._mount
         );
 
         const headers = {};
@@ -35,8 +37,8 @@ class VaultAppRoleAuth extends VaultBaseAuth {
             secret_id: this.__secretId,
         }, headers).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);
         });

package/src/auth/VaultBaseAuth.js

@@ -4,6 +4,7 @@ const lt = require('long-timeout');
 const prettyMs = require('pretty-ms');
 const AuthToken = require('./AuthToken');
 const errors = require('../errors');
+const safeMessage = require('../safeMessage');
 
 class VaultBaseAuth {
 
@@ -44,8 +45,8 @@ class VaultBaseAuth {
 
                 if (this.__authToken.isRenewable()) {
                     this._log.debug(
-                        'setting refresh timer for token %s',
-                        authToken.getId()
+                        'setting refresh timer for token (accessor=%s)',
+                        authToken.getAccessor()
                     );
                     this.__setupTokenRefreshTimer(this.__authToken);
                 }
@@ -106,8 +107,10 @@ class VaultBaseAuth {
             }).catch(err => {
                 this.__setupTokenRefreshTimer(authToken);
 
-                this._log.error(`Cannot refresh auth token with "${authToken.getAccessor()}" accessor. Error: ${err.message}`);
-                this._log.error(err);
+                // Only the safe message: the error object itself used to be logged too, and a
+                // request-promise error carries the request options (the X-Vault-Token header)
+                // and a non-2xx response body (GHSA-2vr8-g4vw-7xpm).
+                this._log.error(`Cannot refresh auth token with "${authToken.getAccessor()}" accessor. Error: ${safeMessage(err)}`);
             });
         }, timer);
 
@@ -131,7 +134,7 @@ class VaultBaseAuth {
                 return this._getTokenEntity(authToken.getId());
             })
             .catch((reason) => {
-                this._log.error('token renew failed: %s', reason.message);
+                this._log.error('token renew failed: %s', safeMessage(reason));
                 throw reason;
             });
     }

package/src/auth/VaultIAMAuth.js

@@ -99,8 +99,8 @@ class VaultIAMAuth extends VaultBaseAuth {
             })
             .then((response) => {
                 this._log.debug(
-                    'receive token: %s',
-                    response.auth.client_token
+                    'received token (accessor=%s)',
+                    response.auth.accessor
                 );
                 return this._getTokenEntity(response.auth.client_token)
             })

package/src/auth/VaultKubernetesAuth.js

@@ -27,18 +27,15 @@ class VaultKubernetesAuth extends VaultBaseAuth {
 
         const k8sJwtToken = fs.readFileSync(this.__tokenPath).toString();
         this._log.debug(
-            'receive K8s token: %s',
-            k8sJwtToken
+            'read K8s service-account JWT from "%s" (%d bytes)',
+            this.__tokenPath, k8sJwtToken.length
         );
 
         return this.__apiClient.makeRequest('POST', `/auth/${this._mount}/login`, {
             role: this.__role,
             jwt: k8sJwtToken,
         }).then((res) => {
-            this._log.debug(
-                'receive token: %s',
-                res.auth.client_token
-            );
+            this._log.debug('received Vault client token from Kubernetes login');
 
             return this._getTokenEntity(res.auth.client_token);
         });

package/src/kvTransform.js

@@ -0,0 +1,92 @@
+'use strict';
+
+const { trimTrailingSlashes } = require('./slashes');
+
+/**
+ * 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 = trimTrailingSlashes(mount);
+
+    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 };

package/src/safeMessage.js

@@ -0,0 +1,33 @@
+'use strict';
+
+const { StatusCodeError } = require('request-promise/errors');
+
+/**
+ * A message for `err` that is safe to log or to embed in another error's message
+ * (GHSA-2vr8-g4vw-7xpm).
+ *
+ * request-promise's StatusCodeError message is `"<status> - <JSON body>"`, and a non-2xx Vault
+ * body can still carry secret material: a transit batch decrypt with one bad item answers 400
+ * with the other items' plaintexts in `data.batch_results`. So for those only the status and
+ * Vault's own `errors` strings are kept. Any other error's message is returned unchanged, and a
+ * rejection value that is not an error (`undefined`, a string) is stringified, so the catch
+ * handler logging it cannot throw.
+ *
+ * @param {*} err
+ * @returns {string}
+ */
+function safeMessage(err) {
+    if (!(err instanceof StatusCodeError)) {
+        return err && err.message !== undefined ? err.message : String(err);
+    }
+
+    const body = err.error;
+    if (!body || typeof body !== 'object' || !Array.isArray(body.errors)) {
+        return `${err.statusCode} - (response body omitted)`;
+    }
+
+    const vaultErrors = body.errors.filter((e) => typeof e === 'string');
+    return `${err.statusCode} - ${JSON.stringify({ errors: vaultErrors })}`;
+}
+
+module.exports = safeMessage;

package/src/slashes.js

@@ -0,0 +1,32 @@
+'use strict';
+
+// Slash trimming without a regex: /\/+$/ is tried at every position of a run of slashes, so it is
+// quadratic on a long run that does not end the string ('a' + '/'.repeat(40000) + 'x' takes
+// half a second), and its inputs (namespace, engines keys, paths, detection responses) come from
+// outside the library (CodeQL js/polynomial-redos).
+
+/**
+ * @param {string} value
+ * @returns {string} `value` without trailing slashes
+ */
+function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value[end - 1] === '/') {
+        end--;
+    }
+    return value.slice(0, end);
+}
+
+/**
+ * @param {string} value
+ * @returns {string} `value` without leading or trailing slashes
+ */
+function trimSlashes(value) {
+    let start = 0;
+    while (start < value.length && value[start] === '/') {
+        start++;
+    }
+    return trimTrailingSlashes(value.slice(start));
+}
+
+module.exports = { trimTrailingSlashes, trimSlashes };