node-vault-client 2.3.0 → 3.0.1

package/README.md

@@ -16,13 +16,11 @@ npm install --save node-vault-client
 
 ### Requirements
 
-Node.js >= 18 — the client uses the native `fetch` API.
+Node.js >= 20.19.0 — the client uses the native `fetch` API. Node 18 support was dropped in 3.0.0
+(Node 18 reached end-of-life on 2025-04-30 and no longer receives security patches from the
+Node.js project); see [CHANGELOG.md](CHANGELOG.md) for details.
 
-> **Node.js 18 sunset notice:** this is the last release of node-vault-client to support Node 18.
-> Node 18 reached end-of-life on 2025-04-30 and no longer receives security patches from the
-> Node.js project. Running this version under Node 18 emits a one-time process warning
-> (`NodeVaultClientNode18Deprecation`); the next major release raises the minimum to
-> Node.js >= 20.19.0. See [CHANGELOG.md](CHANGELOG.md) for details.
+Upgrading from 2.x? [MIGRATION.md](MIGRATION.md) lists what can need a change and what to check.
 
 ### TypeScript
 
@@ -367,19 +365,31 @@ on the next call — no background timer at all. Two reasons to want that:
 Renewal off means the token is allowed to expire, and what happens next depends on whether your
 backend can obtain a *fresh* credential unaided:
 
-| backend | on expiry with `renewal: false` |
-| --- | --- |
-| `kubernetes`, `iam`, `jwt` with `jwtPath`/`jwtProvider` | clean re-login — the JWT or AWS credential is re-acquired, so this is the intended case |
-| `appRole` | re-login **replays the same `secret_id`**. Fine for a reusable one; with Vault's recommended hardening (`secret_id_num_uses=1`, or a short `secret_id_ttl`) the second login is rejected |
-| `jwt` with a literal `jwt` | replays the same JWT, so it works only until the IdP-issued token expires |
-| `token` | **cannot re-authenticate at all.** The client raises `AuthTokenExpiredError` from then on, permanently |
+| backend | on expiry with `renewal: false` | at max TTL with renewal enabled |
+| --- | --- | --- |
+| `kubernetes`, `iam`, `jwt` with `jwtPath`/`jwtProvider` | clean re-login — the JWT or AWS credential is re-acquired, so this is the intended case | clean re-login on the next call after the client-side expiry deadline |
+| `appRole` | re-login **replays the same `secret_id`**. Fine for a reusable one; with Vault's recommended hardening (`secret_id_num_uses=1`, or a short `secret_id_ttl`) the second login is rejected | re-login replays the same `secret_id`; a single-use or expired secret is rejected |
+| `jwt` with a literal `jwt` | replays the same JWT, so it works only until the IdP-issued token expires | replays the same JWT; once it expires, login is rejected |
+| `token` | **cannot re-authenticate at all.** The client raises `AuthTokenExpiredError` from then on, permanently | **cannot re-authenticate at all.** The client raises `AuthTokenExpiredError` after the max-TTL expiry |
+
+#### Tokens that reach their maximum TTL
+
+Vault stops extending a renewable token when it reaches its maximum TTL. The client uses Vault's
+absolute `expire_time` when available, treats `ttl: 0` as expired immediately, and stops background
+renewal when successive absolute expiry deadlines do not materially advance. Because Vault reports
+whole-second TTLs, the scheduler also compares the reported TTL with the elapsed renewal interval;
+short periodic tokens keep renewing even when each expiry advance is one second or less. A
+`renewalIncrement` that meaningfully shortens the expiry still schedules from the new deadline. For positive TTLs above 60 seconds, the client keeps a one-minute
+safety margin for requests in flight; TTLs of 60 seconds or less have no margin. The next call after
+the client-side expiry deadline re-authenticates, as shown in the table above.
 
 Two consequences worth stating plainly:
 
-* For `token` auth this **is** a behaviour change, not a no-op. A renewable token handed to `token`
-  auth is renewed indefinitely today; with `renewal: false` it expires and every later call rejects
-  for the life of the process. `close()` does not reset it — recovery means
-  `VaultClient.clear(name)` and booting again.
+* **For `token` auth, there is no fresh credential for re-authentication.** With `renewal: false`,
+  an otherwise renewable token is allowed to expire without a background renewal. With renewal
+  enabled, the client stops the background loop once Vault no longer extends the expiry materially.
+  After expiry every later call rejects for the life of the process. `close()` does not reset it —
+  recovery means `VaultClient.clear(name)` and booting again.
 * For `appRole` and literal-`jwt`, a login that can no longer succeed is retried on **every**
   subsequent call, since a failed login clears the cached token. That is a failing request per
   `read()`, with no backoff. Prefer `jwtPath`/`jwtProvider`, a reusable `secret_id`, or leaving
@@ -412,8 +422,8 @@ auth: {
 Lower `renewalFraction` values renew earlier and more often, which buys headroom if Vault is briefly
 unreachable. A failed renewal is retried on the same rule against the *same* token, so the waits
 shrink geometrically as the remaining lifetime does — for a 1-hour token that is roughly 12 attempts
-at `0.5` (1800s, 900s, 450s, …) versus 27 at `0.25`, both bottoming out at a 1-second floor just
-before expiry. Higher values renew later and talk to Vault less.
+at `0.5` (1800s, 900s, 450s, …) versus 27 at `0.25`, both bottoming out at a 250 ms minimum delay
+when it still fits before expiry. Higher values renew later and talk to Vault less.
 
 `renewalIncrement` is a request, not a guarantee: Vault grants at most the token's max TTL and may
 return less. Both keys are validated at construction — a `renewalFraction` outside `(0, 1)` or a
@@ -477,7 +487,7 @@ Client constructor function.
 | [options.auth.renewal] | <code>boolean</code> | <code>true</code> | Set `false` to never renew the Vault token in the background; the token is used until it expires and the next call re-authenticates. See [Token renewal](#token-renewal). |
 | [options.auth.renewalFraction] | <code>number</code> | <code>0.5</code> | How much of the token's remaining lifetime to wait before renewing, as a fraction in `(0, 1)`. |
 | [options.auth.renewalIncrement] | <code>number</code> |  | Seconds of extra TTL to request on each renewal, sent as `increment` to `auth/token/renew-self`. Vault caps it at the token's max TTL. |
-| [options.logger] | <code>Object</code> \| <code>false</code> |  | Logger that must implement **all five** of "error", "warn", "info", "debug" and "trace" — an object missing any one of them is silently ignored and the default logger is used instead. The default logger writes to `console`, except `debug`, which is discarded so that sensitive data is never printed. Pass `false` to disable logging entirely. |
+| [options.logger] | <code>Object</code> \| <code>false</code> |  | Logger that must implement **all five** of "error", "warn", "info", "debug" and "trace" — an object missing any one of them is silently ignored and the default logger is used instead. The default logger writes to `console`, except `debug`, which is discarded. Failure logs (`error` level) never include a Vault response body: only the HTTP status and Vault's `errors` strings, which can quote back malformed request fields. Pass `false` to disable logging entirely. |
 
 ##### Custom transport (proxy / self-signed TLS)
 
@@ -634,7 +644,8 @@ Raw request — escape hatch for any Vault backend
 
 Sends the literal API path with no KV path rewriting and no response unwrapping, and
 resolves to the parsed response body. Use it for non-KV backends (e.g. Transit) or when you
-have already constructed the complete Vault API path.
+have already constructed the complete Vault API path. The path is **not validated** (see
+[Path validation](#path-validation)), so never build it from untrusted input.
 
 **Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
 
@@ -906,6 +917,11 @@ const result = await client.request('POST', 'transit/encrypt/my-key', {
 console.log(result.data.ciphertext);
 ```
 
+Transit batch encrypt/decrypt answers HTTP 400 when any item fails, and the rejection's
+`err.error.data.batch_results` still holds the successful items. Pass
+`partial_failure_response_code: 200` (Vault 1.12+) and check each item's `error` if you don't want
+that data on an error path.
+
 ### Lease.getMetadata()
 
 `getMetadata()` is additive — existing code is unaffected.
@@ -941,10 +957,51 @@ rewriting:
 await client.request('GET', 'secret/data/foo');
 ```
 
+### Path validation
+
+The KV methods (`read`, `list`, `write`, `delete`, `update` and the KV v2 helpers) reject a
+path with `InvalidArgumentsError`, before any request is sent, when the URL parser or Vault
+would resolve it to a different path than the one passed:
+
+- an empty path;
+- `?`, `#`, `\`, 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). Vault decodes
+  these and cleans the path again on every redirect hop, so they are rejected rather than decoded;
+- an empty segment such as `a//b` or `a//`, which Vault collapses into the parent path, so
+  `tenants/${id}/key` with an empty `id` would address `tenants/key`;
+- a `.` or `..` segment;
+- a percent-encoded mount (`secre%74/foo`): the `engines` override and mount detection match the
+  path as written, but Vault decodes it, so `secre%74/config` would skip the KV v2 rewrite and
+  reach the mount's own `config` endpoint;
+- a trailing slash on the KV v2 helpers (`deleteVersions`, `undeleteVersions`,
+  `destroyVersions`, `readMetadata`, `deleteMetadata`): Vault applies a metadata call on
+  `tenants/me/` to the key `tenants/me`.
+
+Leading slashes are dropped before the mount is resolved, so `/secret/foo` and `secret/foo`
+address the same key (an `engines` key may be written either way). The other methods keep a
+single trailing slash, as in `list('secret/apps/')`. A percent-encoded segment of a
+multi-segment mount (`team/k%76/foo` for the mount `team/kv`) is rejected too: by the `engines`
+lookup, or after detection with `autoDetect`.
+
+A key name that needs `?` or `#` can still be addressed percent-encoded (`%3F`, `%23`); Vault
+decodes it. A key that needs any other rejected character goes through `request()`, as does a
+specific KV v2 version, which used to work as `read('secret/foo?version=2')`:
+`request('GET', 'secret/data/foo?version=2')`. These checks apply in every mode (passthrough,
+`engines`, `autoDetect`). `request()` sends its path literally and does not apply them.
+
+Still validate lower-trust input before building a path from it: these checks only stop a path
+from reaching a different Vault path than the one it names, not a caller from naming another
+tenant's secret.
+
+A validation error's message says which rule failed but does not include the path, because the
+KV methods log the message at `error` level.
+
 ### Mount detection caching
 
 - Each canonical mount is detected once and then cached for the life of the `VaultClient` instance. The cache is a bounded LRU with a fixed cap of 500 mounts (not configurable through client options); a long-lived client that touches more than 500 distinct mounts evicts the least-recently-used entries, and an evicted mount is detected again on its next use.
 - Concurrent first-touch requests for the same mount share a single in-flight detection promise.
+- A detection response without a string `path` and `type` fails the call with `VaultError` and nothing is cached. A well-formed answer is cached only when its mount contains the requested path; when it does not, that caller gets `InvalidArgumentsError` and callers sharing the detection are unaffected. Auth mounts are cached as `auth/<mount>`, so they never collide with a secrets mount of the same name, and a mount in a child namespace is keyed relative to `api.namespace`.
 - The detection endpoint used is `GET sys/internal/ui/mounts/<path>` (readable by any authenticated token).
 - When the token lacks permission on that endpoint, set `api.engines` to skip detection.
 
@@ -970,10 +1027,10 @@ try {
 | Class | Extends | When thrown |
 |---|---|---|
 | `VaultError` | `Error` | Base class for every error below. Raised directly when mount detection fails (e.g. permission denied) and no `api.engines` override was provided. |
-| `VaultHttpError` | `VaultError` | Vault answered with a non-2xx status. Carries the status as `statusCode` and the parsed body as `error`. |
-| `InvalidArgumentsError` | `VaultError` | Bad arguments or configuration: `boot()` called without options, an unknown instance name passed to `get()`, an unsupported `auth.type`, invalid renewal options, or an invalid node-config substitution map. |
+| `VaultHttpError` | `VaultError` | Vault answered with a non-2xx status. Carries the status as `statusCode` and the parsed body as `error`. `message` (`"<status> - <raw body text>"`) and `error` hold the full response body, which can include secret material (e.g. a partially failed transit batch), so log `statusCode` and `error.errors` rather than the error object itself. |
+| `InvalidArgumentsError` | `VaultError` | Bad arguments or configuration: `boot()` called without options, an unknown instance name passed to `get()`, an unsupported `auth.type`, invalid renewal options, an invalid node-config substitution map, or a KV method path that fails [path validation](#path-validation). |
 | `InvalidAWSCredentialsError` | `InvalidArgumentsError` | `auth.config.credentials` was supplied but is not a usable `accessKeyId` / `secretAccessKey` pair. |
-| `AuthTokenExpiredError` | `VaultError` | The Vault token expired and the backend cannot obtain a new one. `token` auth can never re-authenticate; other backends reach this only with `renewal: false` and a credential they cannot replay. |
+| `AuthTokenExpiredError` | `VaultError` | The Vault token expired and the backend cannot obtain a new one. `token` auth can never re-authenticate and reaches this error at max TTL even with renewal enabled; other backends can also reach it when re-authentication is disabled or their credential can no longer be replayed. |
 | `UnsupportedOperationError` | `VaultError` | A v2-only method (`deleteVersions`, `undeleteVersions`, `destroyVersions`, `readMetadata`, `deleteMetadata`) was called against a mount that did not resolve as KV v2. |
 
 ## Contributing

package/index.d.ts

@@ -127,5 +127,6 @@ declare namespace VaultClient {
         isExpired(): boolean;
         isRenewable(): boolean;
         getExpiresAt(): number | null;
+        getTtlSeconds?(): number | null;
     }
 }

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "node-vault-client",
-  "version": "2.3.0",
+  "version": "3.0.1",
   "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"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.19.0"
   },
   "main": "src/VaultClient.js",
   "types": "index.d.ts",
@@ -45,29 +45,29 @@
   "author": "Namecheap <opensource@namecheap.com>",
   "license": "Apache-2.0",
   "dependencies": {
-    "@aws-sdk/credential-providers": "^3.1100.0",
+    "@aws-sdk/credential-providers": "^3.1130.0",
     "aws4": "^1.13.2",
     "long-timeout": "^0.1.1"
   },
   "peerDependencies": {
-    "config": ">=1 <4"
+    "config": ">=1 <5"
   },
   "overrides": {
-    "serialize-javascript": "^7.0.7",
+    "serialize-javascript": "^7.1.4",
     "glob": "^13.0.0",
     "diff": "^8.0.3",
-    "brace-expansion": "^5.0.9",
+    "brace-expansion": "^5.0.12",
     "js-yaml": "^4.3.2"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.5",
-    "c8": "^10.1.3",
+    "@eslint/js": "^10.0.1",
+    "c8": "^12.0.0",
     "chai": "^6.2.2",
     "deep-freeze": "^0.0.1",
-    "eslint": "^9.39.5",
+    "eslint": "^10.10.0",
     "globals": "^17.8.0",
     "lodash": "^4.18.1",
-    "mocha": "^11.7.6",
+    "mocha": "^12.0.0",
     "sinon": "^22.1.0",
     "sinon-chai": "^4.0.1",
     "typescript": "^7.0.2"

package/src/MountResolver.js

@@ -1,6 +1,8 @@
 'use strict';
 
 const { VaultError, InvalidArgumentsError } = require('./errors');
+const safeMessage = require('./safeMessage');
+const { trimTrailingSlashes, trimSlashes } = require('./slashes');
 
 // Default cap for the mount cache. Real deployments talk to a handful of static
 // mounts, so this is generous headroom; the cap exists so that a long-lived
@@ -8,6 +10,32 @@ const { VaultError, InvalidArgumentsError } = require('./errors');
 // cache — and the per-resolve lookup cost — without bound (issue #108).
 const DEFAULT_MAX_CACHE_SIZE = 500;
 
+/** 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 {
+        return path;
+    }
+}
+
 /**
  * Resolves the KV engine version for a given secret path.
  *
@@ -23,10 +51,15 @@ const DEFAULT_MAX_CACHE_SIZE = 500;
  * @param {Object}   [opts]              - additional options
  * @param {boolean}  [opts.disabled]     - if true, always return passthrough (version 1)
  * @param {number}   [opts.maxCacheSize] - LRU cap for the mount cache (default 500)
+ * @param {string}   [opts.namespace]    - the client's Vault namespace (X-Vault-Namespace)
  */
 class MountResolver {
     constructor(detectFn, enginesOverride, logger, opts) {
         this.__detectFn = detectFn;
+        // 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}/` : '';
         this.__log = logger;
         this.__disabled = opts && opts.disabled === true;
         // Validate before use: a non-positive cap would make the eviction loop in
@@ -43,10 +76,11 @@ class MountResolver {
 
         // The engines map is immutable after construction: normalize and sort the
         // entries once (longest raw prefix first, matching the previous per-call
-        // sort) instead of re-sorting on every resolve().
+        // sort) instead of re-sorting on every resolve(). 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]) => [prefix.replace(/\/+$/, ''), Number(version)]);
+            .map(([prefix, version]) => [trimSlashes(prefix), Number(version)]);
 
         // LRU cache: canonical mount path (no trailing slash) -> { mount, version, type }.
         // Map iteration order is insertion order; hits are re-inserted to refresh
@@ -66,6 +100,10 @@ class MountResolver {
         // 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);
@@ -86,8 +124,15 @@ class MountResolver {
         //    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);
+        return this.__detectWithCache(interimKey, path).then((entry) => {
+            if (!containsPath(entry.mount, path)) {
+                throw encodedMountError(entry.mount);
+            }
+            return entry;
+        });
     }
 
     // -------------------------------------------------------------------------
@@ -101,7 +146,7 @@ class MountResolver {
      */
     __enginesOverrideLookup(path) {
         for (const [prefix, version] of this.__engines) {
-            if (path === prefix || path.startsWith(prefix + '/')) {
+            if (containsPath(prefix, path)) {
                 return { mount: prefix, version, type: 'kv' };
             }
         }
@@ -164,7 +209,7 @@ class MountResolver {
             // 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 + '/')) {
+                if (containsPath(entry.mount, path)) {
                     return entry;
                 }
                 // The shared detection resolved to a different mount — start our own.
@@ -181,8 +226,16 @@ class MountResolver {
                     throw new Error('Unexpected empty detection response');
                 }
 
-                const canonicalMount = (info.path || interimKey).replace(/\/+$/, '');
-                const type = info.type || 'unknown';
+                // Require a mounts-endpoint shape (string path and type) and never fall back
+                // to a caller-derived key or a default type. 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' && optVersion === '2') ? 2 : 1;
@@ -190,8 +243,11 @@ class MountResolver {
                 const entry = { mount: canonicalMount, version, type };
                 this.__log.debug('MountResolver: detected %s as type=%s version=%d', canonicalMount, type, version);
 
-                // Store in persistent cache (bounded LRU)
-                this.__cacheStore(canonicalMount, entry);
+                // 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.__cacheStore(canonicalMount, entry);
+                }
                 // Clear in-flight
                 this.__inflight.delete(interimKey);
                 return entry;
@@ -199,9 +255,12 @@ class MountResolver {
             .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; the original error stays on `cause`.
                 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.'
+                    `Failed to detect KV engine version for mount "${interimKey}" (path: ${path}): ${safeMessage(err)}. ` +
+                    'Set api.engines or disable autoDetect to bypass detection.',
+                    { cause: err }
                 );
             });
 
@@ -209,6 +268,26 @@ class MountResolver {
         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.
      */

package/src/VaultApiClient.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const errors = require('./errors');
+const { trimTrailingSlashes } = require('./slashes');
 
 /**
  * Joins URL segments with single slashes while preserving the leading
@@ -14,7 +15,7 @@ function joinUrl(...parts) {
                 segment = segment.replace(/^\/+/, '');
             }
             if (i < parts.length - 1) {
-                segment = segment.replace(/\/+$/, '');
+                segment = trimTrailingSlashes(segment);
             }
             return segment;
         })

package/src/VaultClient.js

@@ -12,9 +12,8 @@ const VaultKubernetesAuth = require('./auth/VaultKubernetesAuth');
 const VaultJwtAuth = require('./auth/VaultJwtAuth');
 const MountResolver = require('./MountResolver');
 const { rewritePath, normalizeResponse } = require('./kvTransform');
-const { warnIfNode18 } = require('./checkNodeVersion');
-
-warnIfNode18();
+const safeMessage = require('./safeMessage');
+const { trimTrailingSlashes } = require('./slashes');
 
 const noop = () => {};
 const vaultInstances = {};
@@ -49,6 +48,74 @@ function optionsDigest(options) {
     return crypto.createHash('sha256').update(fingerprintOptions(options)).digest('hex');
 }
 
+// fetch() parses the joined URL per the WHATWG URL Standard: '?' starts the query, '#' the
+// fragment, '\' is a path separator for http(s), tab/LF/CR are deleted anywhere and trailing
+// C0 controls and spaces are stripped. Any of these lets a KV path address a different key.
+// eslint-disable-next-line no-control-regex
+const UNSAFE_KV_PATH_CHARS = /[?#\\\u0000-\u001f\u007f]/;
+
+/**
+ * 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).
+ *
+ * fetch() removes '.' and '..' segments, and Vault redirects a raw '//' to the collapsed path,
+ * which fetch() follows (a 301 on Vault 1.x turns a write into a read, a 307 on 2.x writes the
+ * parent key). Encoded forms are rejected rather than decoded: Vault decodes %2e and %2f before
+ * its KV v2 engine resolves '..' and collapses empty segments, and Vault 2.x decodes and
+ * path-cleans 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.
+ *
+ * One trailing slash is allowed (list() addresses a folder with it, and the other methods
+ * pass it through byte for byte), except on the KV v2 helpers: those always address a single
+ * key, and Vault applies a metadata call on 'tenants/me/' to the key 'tenants/me', so
+ * deleteMetadata() would delete it. Unpaired surrogates are rejected because fetch() encodes
+ * every one of them as U+FFFD.
+ *
+ * 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, so 'secre%74/config' would skip
+ * the KV v2 rewrite and reach the mount's own config endpoint.
+ *
+ * @param {*} path - caller-supplied secret path
+ * @param {boolean} allowTrailingSlash - false for the KV v2 helpers
+ * @returns {string} the path without leading slashes, which VaultApiClient drops from the URL
+ *      anyway; 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, allowTrailingSlash) {
+    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(' ') || !path.isWellFormed()) {
+        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');
+    }
+    const segments = (allowTrailingSlash ? trimmed.replace(/\/$/, '') : trimmed).split('/');
+    if (segments.some((segment) => segment === '' || segment === '.' || segment === '..')) {
+        throw new errors.InvalidArgumentsError(
+            'Invalid secret path: empty, \'.\' and \'..\' segments are not allowed ' +
+            '(nor a trailing slash in the KV v2 helpers)'
+        );
+    }
+    return trimmed;
+}
+
 class VaultClient {
 
     /**
@@ -130,6 +197,7 @@ class VaultClient {
 
         this.__resolver = new MountResolver(detectFn, engines, this.__log, {
             disabled: resolverDisabled,
+            namespace,
         });
     }
 
@@ -344,11 +412,22 @@ class VaultClient {
      *      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}>}
+     *      rejects with InvalidArgumentsError, before any request, for an unsafe KV path
      * @private
      */
     __resolveAndRequest(op, method, path, data, extraHeaders, options) {
         const { raw = false, v2Only = false, wrapData = false } = options || {};
 
+        // KV paths are validated before the token fetch, mount resolution and the autoDetect
+        // detection request; request() (raw) keeps its documented literal-path semantics.
+        if (!raw) {
+            try {
+                path = assertSafeKvPath(path, !v2Only);
+            } catch (err) {
+                return Promise.reject(err);
+            }
+        }
+
         return this.__auth.getAuthToken()
             .then((token) => {
                 const headers = Object.assign({}, this.getHeaders(token), extraHeaders || {});
@@ -401,10 +480,17 @@ class VaultClient {
      * @private
      */
     __logicalPath(path, mount) {
-        const prefix = mount.replace(/\/+$/, '');
+        const prefix = trimTrailingSlashes(mount);
         if (path === prefix) return '';
         if (path.startsWith(prefix + '/')) return path.slice(prefix.length + 1);
-        return path;
+        // 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'
+        );
     }
 
     // -------------------------------------------------------------------------
@@ -425,7 +511,7 @@ class VaultClient {
                 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;
             });
     }
@@ -445,7 +531,7 @@ class VaultClient {
                 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;
             });
     }
@@ -465,7 +551,7 @@ class VaultClient {
                 return body;
             })
             .catch((reason) => {
-                this.__log.error('write secret failed: %s', reason.message);
+                this.__log.error('write secret failed: %s', safeMessage(reason));
                 throw reason;
             });
     }
@@ -487,7 +573,7 @@ class VaultClient {
                 return body;
             })
             .catch((reason) => {
-                this.__log.error('delete secret failed: %s', reason.message);
+                this.__log.error('delete secret failed: %s', safeMessage(reason));
                 throw reason;
             });
     }
@@ -512,14 +598,15 @@ class VaultClient {
             { 'Content-Type': 'application/merge-patch+json' }, { wrapData: true })
             .then(({ body }) => body)
             .catch((reason) => {
-                this.__log.error('update secret failed: %s', reason.message);
+                this.__log.error('update secret failed: %s', safeMessage(reason));
                 throw reason;
             });
     }
 
     /**
      * Raw request — literal path, no path rewriting or response unwrapping.
-     * Returns the parsed body directly.
+     * Returns the parsed body directly. The path is not validated: never build it from
+     * untrusted input.
      *
      * @param {string} method - HTTP method
      * @param {string} path   - literal API path
@@ -531,7 +618,7 @@ class VaultClient {
         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);
+                this.__log.error('raw request failed: %s', safeMessage(reason));
                 throw reason;
             });
     }
@@ -552,7 +639,7 @@ class VaultClient {
         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);
+                this.__log.error('deleteVersions failed: %s', safeMessage(reason));
                 throw reason;
             });
     }
@@ -569,7 +656,7 @@ class VaultClient {
         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);
+                this.__log.error('undeleteVersions failed: %s', safeMessage(reason));
                 throw reason;
             });
     }
@@ -586,7 +673,7 @@ class VaultClient {
         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);
+                this.__log.error('destroyVersions failed: %s', safeMessage(reason));
                 throw reason;
             });
     }
@@ -605,7 +692,7 @@ class VaultClient {
                 return normalizeResponse(2, 'readMetadata', body);
             })
             .catch((reason) => {
-                this.__log.error('readMetadata failed: %s', reason.message);
+                this.__log.error('readMetadata failed: %s', safeMessage(reason));
                 throw reason;
             });
     }
@@ -621,7 +708,7 @@ class VaultClient {
         this.__log.debug('deleteMetadata %s', path);
         return this.__v2Only('deleteMetadata', 'DELETE', path, null)
             .catch((reason) => {
-                this.__log.error('deleteMetadata failed: %s', reason.message);
+                this.__log.error('deleteMetadata failed: %s', safeMessage(reason));
                 throw reason;
             });
     }

package/src/VaultNodeConfig.js

@@ -8,6 +8,26 @@ function isObject(value) {
     return value !== null && typeof value === 'object';
 }
 
+/**
+ * Resolves NODE_CONFIG_DIR the same way `config`'s own `util.initParam` historically did —
+ * a `--NODE_CONFIG_DIR=value` command-line argument, then the environment variable, then
+ * `defaultValue` — implemented directly rather than through `config.util.initParam`, which
+ * config 4.x removed from its public API without documenting the removal (`config.util` is
+ * now a `ConfigUtils` instance with no `initParam` method at all; calling it throws
+ * "config.util.initParam is not a function"). This also means resolution no longer depends
+ * on which `config` major is installed.
+ *
+ * @private
+ */
+function resolveConfigDir(defaultValue) {
+    const argPrefix = '--NODE_CONFIG_DIR=';
+    const cmdLineArg = process.argv.slice(2).find((arg) => arg.startsWith(argPrefix));
+    if (cmdLineArg !== undefined) {
+        return cmdLineArg.slice(argPrefix.length);
+    }
+    return process.env.NODE_CONFIG_DIR || defaultValue;
+}
+
 function isPlainObject(value) {
     if (!isObject(value)) {
         return false;
@@ -112,7 +132,7 @@ class VaultNodeConfig {
      * @private
      */
     __getSubstitutionMap() {
-        let configDir = this.__nodeConfig.util.initParam('NODE_CONFIG_DIR', path.join(process.cwd(), 'config'));
+        let configDir = resolveConfigDir(path.join(process.cwd(), 'config'));
         if (configDir.indexOf('.') === 0) {
             configDir = path.join(process.cwd(), configDir);
         }

package/src/auth/AuthToken.js

@@ -12,6 +12,10 @@ class AuthToken {
      * @param {int} explicitMaxTtl - in seconds
      * @param {int} numUses
      * @param {boolean} isRenewable
+     * @param {int|null} expiresAtMilliseconds - precise expiry time when available
+     * @param {int|null} ttl - remaining lifetime reported by Vault, when available
+     * @param {boolean} hasPreciseExpiry - true when expiry came from Vault's expire_time
+     * @param {int|null} unadjustedExpiresAtMilliseconds - Vault's expiry before the client safety margin
      */
     constructor(
         id,
@@ -20,35 +24,58 @@ class AuthToken {
         expiresAt,
         explicitMaxTtl,
         numUses,
-        isRenewable
+        isRenewable,
+        expiresAtMilliseconds = null,
+        ttl = null,
+        hasPreciseExpiry = false,
+        unadjustedExpiresAtMilliseconds = null
     ) {
         this.__id = id;
         this.__accessor = accessor;
         this.__createdAt = createdAt;
-        this.__expiresAt = expiresAt;
+        this.__expiresAtMilliseconds = expiresAt === null
+            ? expiresAtMilliseconds
+            : (expiresAtMilliseconds ?? expiresAt * 1000);
+        this.__expiresAt = this.__expiresAtMilliseconds === null
+            ? null
+            : Math.floor(this.__expiresAtMilliseconds / 1000);
+        this.__unadjustedExpiresAtMilliseconds = unadjustedExpiresAtMilliseconds
+            ?? this.__expiresAtMilliseconds;
+        this.__hasPreciseExpiry = hasPreciseExpiry;
+        this.__ttlSeconds = Number.isFinite(ttl) ? ttl : null;
         this.__explicitMaxTtl = explicitMaxTtl;
         this.__numUses = numUses;
-        this.__isRenewable = isRenewable;
+        this.__isRenewable = isRenewable
+            && ttl !== 0
+            && this.__expiresAtMilliseconds !== null;
     }
 
     static fromResponse(response) {
         const data = response.data;
+        const unadjustedExpiresAtMilliseconds = AuthToken.__parseRfc3339Milliseconds(data.expire_time);
+        const hasPreciseExpiry = unadjustedExpiresAtMilliseconds !== null;
+        const expiresAtMilliseconds = AuthToken.__resolveExpiresAtMilliseconds(data, unadjustedExpiresAtMilliseconds);
 
         return new AuthToken(
             data.id,
             data.accessor,
             data.creation_time,
-            AuthToken.__resolveExpiresAt(data),
+            null,
             data.explicit_max_ttl,
             data.num_uses,
-            data.renewable !== undefined ? data.renewable : false
+            data.renewable !== undefined ? data.renewable : false,
+            expiresAtMilliseconds,
+            data.ttl,
+            hasPreciseExpiry,
+            unadjustedExpiresAtMilliseconds
         );
     }
 
     /**
-     * Resolve the UNIX timestamp (seconds) at which the client should treat the token
-     * as expired, shifted earlier by a network-latency safety margin so renewal happens
-     * before the real expiry.
+     * Resolve the UNIX timestamp (milliseconds) at which the client should treat the token
+     * as expired. A zero TTL is expired when received because the reported TTL is truncated
+     * and Vault's wall clock may differ from the client's. For longer TTLs, keep the existing
+     * one-minute margin only when more than one minute remains.
      *
      * Prefers Vault's authoritative `expire_time` (RFC3339), which is the documented
      * absolute expiry. Falls back to `(last_renewal_time || creation_time) + ttl` for
@@ -57,37 +84,41 @@ class AuthToken {
      *
      * @private
      * @param {Object} data - the `data` object of a token lookup response
-     * @returns {int|null} null when the token never expires (ttl === 0)
+     * @param {number|null} expireTime - parsed Vault expiry in milliseconds
+     * @returns {int|null} client expiry in milliseconds, or null when ttl is 0 without expire_time
      */
-    static __resolveExpiresAt(data) {
-        if (data.ttl === 0) {
-            return null;
-        }
-
+    static __resolveExpiresAtMilliseconds(data, expireTime) {
         const networkLatency = 60;
-        const margin = data.ttl > networkLatency ? networkLatency : 0;
 
-        const expireTime = AuthToken.__parseRfc3339Seconds(data.expire_time);
         if (expireTime !== null) {
-            return expireTime - margin;
+            if (data.ttl === 0) {
+                return Date.now();
+            }
+
+            const margin = data.ttl > networkLatency ? networkLatency : 0;
+            return expireTime - margin * 1000;
+        }
+
+        if (data.ttl === 0) {
+            return null;
         }
 
         // Fallback for responses without a usable `expire_time`.
         const creationTime = parseInt(data.last_renewal_time !== undefined ? data.last_renewal_time : data.creation_time, 10);
         const ttl = data.ttl > networkLatency ? data.ttl - networkLatency : data.ttl;
-        return creationTime + parseInt(ttl, 10);
+        return (creationTime + parseInt(ttl, 10)) * 1000;
     }
 
     /**
      * Parse an RFC3339 timestamp (as returned by Vault, up to nanosecond precision with
-     * a timezone offset) into whole UNIX seconds. Returns null for missing, empty,
+     * a timezone offset) into UNIX milliseconds. Returns null for missing, empty,
      * unparseable, or non-positive (e.g. Vault's "0001-01-01T00:00:00Z" zero value) input.
      *
      * @private
      * @param {String} value
      * @returns {int|null}
      */
-    static __parseRfc3339Seconds(value) {
+    static __parseRfc3339Milliseconds(value) {
         if (typeof value !== 'string' || value === '') {
             return null;
         }
@@ -97,8 +128,7 @@ class AuthToken {
             return null;
         }
 
-        const seconds = Math.floor(ms / 1000);
-        return seconds > 0 ? seconds : null;
+        return ms > 0 ? ms : null;
     }
 
     /**
@@ -120,6 +150,12 @@ class AuthToken {
             return false;
         }
 
+        if (this.__hasPreciseExpiry) {
+            return Date.now() >= this.__expiresAtMilliseconds;
+        }
+
+        // Preserve the previous whole-second boundary for tokens that do not carry
+        // Vault's authoritative expire_time.
         return Math.floor(Date.now() / 1000) > this.__expiresAt;
     }
 
@@ -127,7 +163,7 @@ class AuthToken {
      * @returns {boolean}
      */
     isRenewable() {
-        return this.__isRenewable && this.getExpiresAt() !== null;
+        return this.__isRenewable;
     }
 
     /**
@@ -136,6 +172,35 @@ class AuthToken {
     getExpiresAt() {
         return this.__expiresAt;
     }
+
+    /**
+     * @returns {int|null} precise UNIX timestamp in milliseconds, when available
+     */
+    getExpiresAtMilliseconds() {
+        return this.__expiresAtMilliseconds;
+    }
+
+    /**
+     * @returns {int|null} expiry before the safety adjustment, when available
+     */
+    getUnadjustedExpiresAtMilliseconds() {
+        return this.__unadjustedExpiresAtMilliseconds;
+    }
+
+    /**
+     * Return Vault's whole-second TTL when this token came from a lookup response.
+     * @returns {number|null}
+     */
+    getTtlSeconds() {
+        return this.__ttlSeconds;
+    }
+
+    /**
+     * @returns {boolean}
+     */
+    hasPreciseExpiry() {
+        return this.__hasPreciseExpiry;
+    }
 }
 
 module.exports = AuthToken;

package/src/auth/VaultAppRoleAuth.js

@@ -27,9 +27,10 @@ class VaultAppRoleAuth extends VaultBaseAuth {
     }
 
     _authenticate() {
+        // Never log the role_id: for a role with bind_secret_id=false it is the whole login credential.
         this._log.info(
-            'making authentication request: role_id=%s',
-            this.__roleId
+            'making authentication request: approle mount=%s',
+            this._mount
         );
 
         return this.__apiClient.makeRequest('POST', `/auth/${this._mount}/login`, {

package/src/auth/VaultBaseAuth.js

@@ -9,7 +9,10 @@ const AuthToken = require('./AuthToken');
 
 /** Renew at the halfway point of the token's remaining lifetime. */
 const DEFAULT_RENEWAL_FRACTION = 0.5;
+/** Maximum rounding difference allowed when comparing expiry movement with a renewal interval. */
+const MAX_EXPIRY_JITTER_MS = 1000;
 const errors = require('../errors');
+const safeMessage = require('../safeMessage');
 
 /**
  * Formats a millisecond duration as a short human-readable string
@@ -28,6 +31,81 @@ function humanizeMs(ms) {
     return `${hours}h ${totalMinutes % 60}m`;
 }
 
+/**
+ * Read precise expiry when available, preserving the public AuthToken interface fallback.
+ * @param {AuthToken} authToken
+ * @returns {number|null}
+ * @private
+ */
+function tokenExpiryMilliseconds(authToken) {
+    if (typeof authToken.getExpiresAtMilliseconds === 'function') {
+        const expiry = authToken.getExpiresAtMilliseconds();
+        if (Number.isFinite(expiry)) {
+            return expiry;
+        }
+    }
+
+    const expiry = authToken.getExpiresAt();
+    return typeof expiry === 'number' && Number.isFinite(expiry) ? expiry * 1000 : null;
+}
+
+/**
+ * Read Vault's unadjusted absolute expiry when available; duck-typed tokens fall back to their
+ * public expiry in seconds.
+ * @param {AuthToken} authToken
+ * @returns {number|null}
+ * @private
+ */
+function tokenUnadjustedExpiryMilliseconds(authToken) {
+    if (typeof authToken.getUnadjustedExpiresAtMilliseconds === 'function') {
+        const expiry = authToken.getUnadjustedExpiresAtMilliseconds();
+        if (Number.isFinite(expiry)) {
+            return expiry;
+        }
+    }
+
+    return tokenExpiryMilliseconds(authToken);
+}
+
+/**
+ * Read Vault's whole-second TTL when the token implementation exposes it.
+ * @param {AuthToken} authToken
+ * @returns {number|null}
+ * @private
+ */
+function tokenTtlSeconds(authToken) {
+    if (typeof authToken.getTtlSeconds !== 'function') {
+        return null;
+    }
+    const ttl = authToken.getTtlSeconds();
+    return typeof ttl === 'number' && Number.isFinite(ttl) ? ttl : null;
+}
+
+/**
+ * Explain why background renewal ended without exposing the token ID.
+ * @param {VaultBaseAuth} auth
+ * @param {AuthToken} authToken
+ * @param {string} reason
+ * @returns {void}
+ * @private
+ */
+function warnRenewalStopped(auth, authToken, reason) {
+    const expiry = tokenExpiryMilliseconds(authToken);
+    const nextAction = expiry === null
+        ? 'expiry is unknown; the cached token remains in use until it is replaced'
+        : auth._reauthenticationAllowed()
+            ? 'the next call after expiry will re-authenticate'
+            : 'the next call after expiry will fail with AuthTokenExpiredError';
+
+    auth._log.warn(
+        'token renewal stopped (accessor=%s): %s; client-side expiry is %s; %s',
+        authToken.getAccessor(),
+        reason,
+        expiry === null ? 'unknown' : new Date(expiry).toISOString(),
+        nextAction
+    );
+}
+
 class VaultBaseAuth {
 
     /**
@@ -254,12 +332,38 @@ class VaultBaseAuth {
             this.__refreshTimeout = null;
         }
 
-        if (!this.__renewalEnabled || !authToken.isRenewable() || authToken.isExpired()) {
+        if (!this.__renewalEnabled) {
+            return;
+        }
+        if (!authToken.isRenewable() || authToken.isExpired()) {
+            warnRenewalStopped(
+                this,
+                authToken,
+                authToken.isExpired() ? 'token already expired' : 'token is not renewable'
+            );
             return;
         }
 
-        const remaining = authToken.getExpiresAt() - Math.floor(Date.now() / 1000);
-        const timer = Math.max(remaining * this.__renewalFraction, 1) * 1000;
+        const expiry = tokenExpiryMilliseconds(authToken);
+        if (expiry === null) {
+            warnRenewalStopped(this, authToken, 'token has no usable expiry');
+            return;
+        }
+
+        const remaining = expiry - Date.now();
+        if (remaining <= 0) {
+            warnRenewalStopped(this, authToken, 'token already expired');
+            return;
+        }
+
+        const timer = Math.max(
+            Math.floor(remaining * this.__renewalFraction),
+            250
+        );
+        if (timer >= remaining) {
+            warnRenewalStopped(this, authToken, 'too little lifetime left to renew');
+            return;
+        }
 
         // A renewal that is still in flight when the token is replaced or cancelled must not
         // act on what it finds when it lands: it would overwrite the newer token, or clear
@@ -267,26 +371,68 @@ class VaultBaseAuth {
         // permanently un-renewed. Anything that supersedes this timer bumps the epoch.
         const epoch = ++this.__renewalEpoch;
         const superseded = () => this.__renewalEpoch !== epoch;
+        const scheduledAt = Date.now();
 
         this.__refreshTimeout = lt.setTimeout(() => {
             if (superseded()) {
                 return;
             }
+            this.__refreshTimeout = null;
 
             this.__renewToken(authToken).then(renewedToken => {
                 if (superseded()) {
                     return;
                 }
                 this.__authToken = renewedToken;
-                this.__setupTokenRefreshTimer(renewedToken);
+                if (!renewedToken.isRenewable() || renewedToken.isExpired()) {
+                    this.__setupTokenRefreshTimer(renewedToken);
+                    return;
+                }
+
+                const previousExpiry = tokenUnadjustedExpiryMilliseconds(authToken);
+                const renewedExpiry = tokenUnadjustedExpiryMilliseconds(renewedToken);
+                const expiryMovement = previousExpiry === null || renewedExpiry === null
+                    ? null
+                    : renewedExpiry - previousExpiry;
+                const previousTtl = tokenTtlSeconds(authToken);
+                const renewedTtl = tokenTtlSeconds(renewedToken);
+                const ttlDidNotDecrease = previousTtl === null || renewedTtl === null
+                    || renewedTtl >= previousTtl;
+                const renewalElapsedMs = Date.now() - scheduledAt;
+                // A max-TTL cap leaves the absolute expiry roughly fixed, while a periodic
+                // renewal moves it forward by about the time spent waiting. Compare the
+                // reported TTL too, so whole-second rounding does not make a short extension
+                // look like a capped token.
+                const expiryAdvancedWithRenewal = expiryMovement !== null
+                    && expiryMovement >= 0
+                    && ttlDidNotDecrease
+                    && Math.abs(expiryMovement - renewalElapsedMs) <= MAX_EXPIRY_JITTER_MS;
+                const expiryMovedMaterially = expiryMovement !== null
+                    && Math.abs(expiryMovement) > MAX_EXPIRY_JITTER_MS;
+
+                if (expiryMovedMaterially || expiryAdvancedWithRenewal) {
+                    this.__setupTokenRefreshTimer(renewedToken);
+                } else {
+                    warnRenewalStopped(
+                        this,
+                        renewedToken,
+                        'Vault did not extend the token (maximum TTL likely reached)'
+                    );
+                }
             }).catch(err => {
                 if (superseded()) {
                     return;
                 }
                 this.__setupTokenRefreshTimer(authToken);
 
-                this._log.error(`Cannot refresh auth token with "${authToken.getAccessor()}" accessor. Error: ${err.message}`);
-                this._log.error(err);
+                const message = `Cannot refresh auth token with "${authToken.getAccessor()}" accessor.`;
+                // Dumping a VaultHttpError would print its raw response body, so it gets the safe
+                // message only. Any other error is logged whole: its stack already has the message.
+                if (err instanceof errors.VaultHttpError) {
+                    this._log.error(`${message} Error: ${safeMessage(err)}`);
+                } else {
+                    this._log.error(message, err);
+                }
             });
         }, timer);
 
@@ -313,7 +459,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/kvTransform.js

@@ -8,6 +8,8 @@
  * normalizeResponse(version, op, body)         -> normalized body
  */
 
+const { trimTrailingSlashes } = require('./slashes');
+
 // Map of op -> v2 path segment inserted between mount and logical path.
 const V2_SEGMENT = {
     read:            'data',
@@ -33,7 +35,7 @@ const V2_SEGMENT = {
  */
 function rewritePath(version, op, mount, logicalPath) {
     // Normalise trailing slash on mount
-    const m = mount.replace(/\/+$/, '');
+    const m = trimTrailingSlashes(mount);
 
     if (version !== 2) {
         // v1 / non-kv: simple concatenation

package/src/safeMessage.js

@@ -0,0 +1,32 @@
+'use strict';
+
+const { VaultHttpError } = require('./errors');
+
+/**
+ * A message for `err` that is safe to log or to embed in another error's message.
+ *
+ * A {@link VaultHttpError}'s own message is `"<status> - <raw body text>"` (kept for
+ * compatibility), 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 VaultHttpError)) {
+        return err && err.message !== undefined ? err.message : String(err);
+    }
+
+    const body = err.error;
+    if (!body || !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 };

package/src/checkNodeVersion.js

@@ -1,27 +0,0 @@
-'use strict';
-
-const NODE_18_DEPRECATION_MESSAGE =
-    'node-vault-client: this is the last release of this package to support Node.js 18. ' +
-    'Node 18 reached end-of-life on 2025-04-30 and no longer receives security patches from ' +
-    'the Node.js project. The next major release of node-vault-client will require ' +
-    'Node.js >= 20.19.0 — see CHANGELOG.md for details.';
-const NODE_18_DEPRECATION_CODE = 'NodeVaultClientNode18Deprecation';
-
-/**
- * Emits a one-time process warning when running on Node.js 18. Called once, at module load,
- * from VaultClient.js — require()'s own module cache is what keeps it to once per process,
- * not any dedup logic here.
- *
- * Takes a `process`-like object (defaulting to the real `process`) purely so tests can assert
- * the behaviour on a stubbed Node version instead of on whatever Node this suite happens to run
- * under.
- */
-function warnIfNode18(proc) {
-    proc = proc || process;
-    const nodeVersion = proc.versions && proc.versions.node;
-    if (typeof nodeVersion === 'string' && /^18\./.test(nodeVersion)) {
-        proc.emitWarning(NODE_18_DEPRECATION_MESSAGE, { code: NODE_18_DEPRECATION_CODE });
-    }
-}
-
-module.exports = { warnIfNode18, NODE_18_DEPRECATION_MESSAGE, NODE_18_DEPRECATION_CODE };