node-vault-client 3.0.1 → 3.1.0

package/README.md

@@ -174,7 +174,7 @@ const vaultClient = VaultClient.boot('main', {
         config: {
             role: 'my-app',                                       // Optional. Role configured in Vault's JWT auth backend; omitted uses the mount's `default_role`
             jwt: process.env.CI_JOB_JWT,                          // Exactly one of `jwt` / `jwtPath` / `jwtProvider` is required (see below)
-            distributedClaimAccessToken: process.env.GRAPH_TOKEN, // Optional. Azure/Entra ID group lookups only (see below); or `distributedClaimAccessTokenProvider`
+            // distributedClaimAccessTokenProvider: () => getGraphAccessToken(), // Optional. Azure/Entra ID group lookups only (see below)
         },
     },
 });
@@ -244,17 +244,28 @@ group lookup rather than anything about your token.
 
 Two optional, mutually exclusive `config` keys supply it. Passing both raises
 `InvalidArgumentsError` at construction; passing neither leaves the login request byte-for-byte
-what it was before these keys existed.
+what it was before these keys existed. A key whose value is `undefined` counts as not passed, so
+`distributedClaimAccessToken: process.env.GRAPH_TOKEN` with the variable unset logs in *without* a
+Graph token — and on a mount/role that needs one, fails at Vault's group lookup. The login log line
+always names the source (`distributed claim access token: literal`, `provider` or `none`), so check
+it first when that happens.
 
 * **`distributedClaimAccessToken`** — a literal Graph access token. It carries exactly the caveat
   the literal `jwt` above does, for the same reason: the value is fixed at construction and every
   re-login re-sends it, so it works until that token expires. Entra access tokens last about an
   hour, which is shorter than most processes — fine for a one-shot script, wrong for a service.
+  Surrounding whitespace is trimmed; an empty, whitespace-only or non-string value raises
+  `InvalidArgumentsError` at construction instead of being sent.
 * **`distributedClaimAccessTokenProvider`** — an (optionally async) function, called fresh at login
   time (never at construction, never cached), returning `string | Promise<string>`. Acquire the
   Graph token inside it — an MSAL client-credentials call, the Azure IMDS managed-identity endpoint
-  — and every login gets a current one. Resolving to a non-string or an empty string raises
-  `InvalidArgumentsError` without sending a login request.
+  — and every login gets a current one. It runs concurrently with the JWT source, so login takes as
+  long as the slower of the two rather than both in turn. Surrounding whitespace is trimmed;
+  resolving to a non-string, an empty or a whitespace-only string raises `InvalidArgumentsError`
+  without sending a login request. If either provider throws or rejects, the client logs which one
+  (`JWT login aborted: "distributedClaimAccessTokenProvider" failed: ...`) and the login rejects with
+  your provider's own error, unchanged. A failing JWT source rejects the login at once, without
+  waiting for this provider; when both fail, the JWT source's error is the one raised.
 
 ```javascript
 const vaultClient = VaultClient.boot('main', {
@@ -368,26 +379,38 @@ backend can obtain a *fresh* credential unaided:
 | 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 |
+| `jwt` with `jwtPath`/`jwtProvider` **and a literal `distributedClaimAccessToken`** | the JWT is fresh but the Graph access token is **replayed**; once it expires (about an hour for Entra ID) Vault's group lookup fails every re-login. Use `distributedClaimAccessTokenProvider` | same: re-login replays the expired Graph token and is rejected |
 | `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.
+Vault stops extending a renewable token when it reaches its maximum TTL: the token's explicit max
+TTL, the role's `token_max_ttl`, or the auth mount's max lease TTL. When a renewal is capped, Vault
+says so in the `renew-self` response, with a warning such as `TTL of "1h" exceeded the effective
+max_ttl of "20m"; TTL value is capped accordingly`. The client stops background renewal on that
+warning and logs `token renewal stopped (accessor=…): Vault capped the renewal at the token's
+maximum TTL`. A renewal without the warning is never treated as capped, however little it moved
+the deadline. That includes short periodic tokens renewed less than a second apart, and a
+`renewalIncrement` that leaves the deadline where it was or brings it closer. Vault's other cap
+warning, `period of "…" exceeded the effective max_ttl of "…"; period value is capped accordingly`,
+does not stop renewal either: it comes with every renewal of a periodic token whose period is above
+the role's `token_max_ttl` or the mount's max lease TTL, and that token stays renewable at the
+shorter period. The next renewal is always scheduled from the new deadline.
+
+The client uses Vault's absolute `expire_time` when available and treats `ttl: 0` as expired
+immediately. Because Vault truncates `ttl` to whole seconds, a token with a period of **1 second**
+reports `ttl: 0` right after each renewal and is treated as expired. Use a period of at least
+2 seconds. 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, 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.
+  enabled, the client stops the background loop once Vault reports that a renewal was capped.
   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**
@@ -423,10 +446,16 @@ Lower `renewalFraction` values renew earlier and more often, which buys headroom
 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 250 ms minimum delay
-when it still fits before expiry. Higher values renew later and talk to Vault less.
+when it still fits before expiry. Higher values renew later and talk to Vault less. A low fraction on a
+short TTL is safe: renewals under a second apart keep working. The 250 ms minimum delay only matters
+once less than 250 ms of lifetime is left, and the client then stops with `too little lifetime left
+to renew`.
 
 `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
+return less. For a non-periodic token the increment *replaces* the remaining lifetime, counted from
+the renewal, so a value below the remaining TTL shortens the token. `renewalIncrement: 1` leaves a
+1-second token that lookup reports as `ttl: 0`, so the client treats it as expired after the first
+renewal; use at least `2`. Periodic tokens ignore the increment and renew to their period. Both keys are validated at construction — a `renewalFraction` outside `(0, 1)` or a
 non-positive/non-integer `renewalIncrement` raises `InvalidArgumentsError` rather than failing later
 inside a background timer.
 
@@ -476,6 +505,7 @@ Client constructor function.
 | options.api.url | <code>String</code> |  | the url of the vault server |
 | [options.api.apiVersion] | <code>String</code> | `v1` |  |
 | [options.api.requestOptions] | <code>Object</code> |  | extra options merged into every HTTP request (see [Custom transport](#custom-transport-proxy--self-signed-tls)) |
+| [options.api.timeout] | <code>number</code> | `120000` | milliseconds a request may take, response headers, body and redirects included, before it rejects with `RequestTimeoutError`; `0` turns the limit off, `null` gives the default (see [Request timeouts](#request-timeouts)) |
 | [options.api.namespace] | <code>String</code> |  | Optional. Vault namespace, sent as the `X-Vault-Namespace` header on **every** request — login, token lookup/renewal, and all secret operations — for every auth type. This is the canonical location; `auth.config.namespace` is still honored for backward compatibility. |
 | [options.api.kv.autoDetect] | <code>boolean</code> | `false` | auto-detect the KV version of each mount on first use (see [KV v2 & generic backends](#kv-v2--generic-backends)) |
 | [options.api.engines] | <code>Object</code> | `{}` | static mount-to-version map, e.g. `{ secret: 2, legacy: 1 }` (see [KV v2 & generic backends](#kv-v2--generic-backends)) |
@@ -530,8 +560,35 @@ bundle undici 7.x, so pin `undici@^7`.
 
 ##### Request timeouts
 
-There is no default timeout. A Vault that accepts the connection and never answers will leave
-`read()` (and every other call) pending indefinitely. Set one through the dispatcher:
+Every request to Vault, including logins, `lookup-self` and background `renew-self`, has to
+finish within `api.timeout` milliseconds: **120 000 (2 minutes) by default**. The limit covers the
+whole request: response headers, the body and any redirects. A request that runs out of time
+rejects with `RequestTimeoutError` (its `timeout` property holds the limit, `cause` the
+`fetch()` rejection). With `api.kv.autoDetect`, a mount detection that times out fails the call
+with the usual detection `VaultError`, with `RequestTimeoutError` on its `cause`. A renewal that
+times out is handled like any other failed renewal.
+
+`api.timeout` is in milliseconds; `null` or leaving it out gives the default, and a value under
+1000 logs a warning in case it was meant as seconds. Anything but an integer from 0 to 2147483647
+raises `InvalidArgumentsError` when the client is created.
+
+The default sits above Vault's own default `max_request_duration` (90 s), so it does not cut
+short a request that a Vault with default settings would still answer. Set it lower to fail
+fast, or higher if your Vault allows longer requests:
+
+```javascript
+const vaultClient = VaultClient.boot('main', {
+    api: { url: 'https://vault.example.com:8200/', timeout: 10000 },
+    auth: { type: 'token', config: { token: '...' } },
+});
+```
+
+`timeout: 0` turns the limit off, as it was before `api.timeout` existed. What remains then
+are the timeouts of the dispatcher `fetch()` uses: Node's default one gives up after 300 s
+without response headers (`TypeError: fetch failed`, `cause.code` `UND_ERR_HEADERS_TIMEOUT`) or
+300 s without body data (`UND_ERR_BODY_TIMEOUT`). Those limits apply per phase, so a body that
+keeps trickling in is never cut off. Any timeouts set on a custom dispatcher still apply
+alongside `api.timeout`, and whichever fires first rejects the request:
 
 ```javascript
 const { Agent } = require('undici');
@@ -545,20 +602,23 @@ const vaultClient = VaultClient.boot('main', {
 });
 ```
 
-A failed request rejects with `TypeError: fetch failed`, with `cause.code` set to
-`UND_ERR_HEADERS_TIMEOUT` or `UND_ERR_BODY_TIMEOUT`.
-
-Do **not** put `signal: AbortSignal.timeout(ms)` in `requestOptions`. It is created once and
-shared by every request the client makes, so it works for the first call and then aborts all
-later ones with `TimeoutError`. Pass a fresh signal per call, or use the dispatcher above.
+A `signal` in `requestOptions` still aborts every request in flight when it fires (with the
+signal's own reason, not `RequestTimeoutError`), so an `AbortController` can cancel requests
+on shutdown. `fetch()` then receives the client's own per-request signal, which follows it. Do **not** use `signal: AbortSignal.timeout(ms)` there: it is created once and
+shared by every request the client makes, so it works for the first calls and then aborts all
+later ones. Use `api.timeout` instead.
 
 ##### Redirects and the Vault token
 
 Requests follow HTTP redirects, because Vault HA clusters answer standby nodes with a 307 to the
 active node. Node's `fetch()` strips only `Authorization`, `Cookie` and `Proxy-Authorization` when
-a redirect crosses origins — `X-Vault-Token` is **not** on that list and is forwarded. A host that
-can answer for `api.url` can therefore redirect the client and receive its Vault token, so treat
-`api.url` (and the DNS and any load balancer in front of it) as trusted infrastructure.
+a redirect crosses origins — `X-Vault-Token` is **not** on that list and is forwarded. A 307 or 308
+also re-sends the request body, so a login is replayed to the redirect target with its credentials:
+the AppRole `secret_id`, the Kubernetes or JWT token, the signed IAM request and, with
+`distributedClaimAccessToken`, a Microsoft Graph access token that is a credential for systems other
+than Vault. A host that can answer for `api.url` can therefore redirect the client and receive its
+Vault token and its login credentials, so treat `api.url` (and the DNS and any load balancer in
+front of it) as trusted infrastructure.
 
 <a name="VaultClient+fillNodeConfig"></a>
 
@@ -783,6 +843,14 @@ the ones it was booted with, the client logs a warning rather than letting the d
 silently. Use [`VaultClient.get(name)`](#VaultClient.get) to fetch an existing instance, or
 [`VaultClient.clear(name)`](#VaultClient.clear) before booting to replace one.
 
+Options are compared as hashes, so no credential is kept for the comparison. Plain objects and
+arrays compare by content, in any key order. Functions and other objects compare by identity, and
+a `Buffer`, `Date`, `URL` or `RegExp` by value. So a logger class instance, an undici `dispatcher`,
+or a logger object built from new functions counts as different even when it would behave the
+same; a plain object that reuses the same functions does not. The warning names the top-level
+options that differ (for example `logger`) and is logged once per instance for each set of them.
+Boot each name once and fetch it with `get()` elsewhere.
+
 **Kind**: static method of [<code>VaultClient</code>](#VaultClient)  
 **Returns**: <code>VaultClient</code>  
 
@@ -1028,10 +1096,11 @@ try {
 |---|---|---|
 | `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`. `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). |
+| `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 `api.timeout`, 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 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. |
+| `RequestTimeoutError` | `VaultError` | A request to Vault did not finish within `api.timeout` milliseconds (see [Request timeouts](#request-timeouts)). Carries the limit as `timeout` and the `fetch()` rejection (a `TimeoutError` DOMException) as `cause`. |
 
 ## Contributing
 

package/index.d.ts

@@ -39,6 +39,8 @@ declare namespace VaultClient {
         apiVersion?: string;
         namespace?: string;
         requestOptions?: Record<string, any>;
+        /** Milliseconds a request may take before it rejects with RequestTimeoutError; `0` turns it off. Default 120000. */
+        timeout?: number | null;
         kv?: { autoDetect?: boolean };
         engines?: Record<string, 1 | 2>;
     }
@@ -79,10 +81,14 @@ declare namespace VaultClient {
         namespace?: string;
     }
 
+    // Either key may be `undefined` (it is then not sent), so a conditionally-set value such as
+    // `process.env.GRAPH_TOKEN` type-checks; setting both is still rejected.
     type JwtDistributedClaimConfig =
-        | { distributedClaimAccessToken?: never; distributedClaimAccessTokenProvider?: never }
-        | { distributedClaimAccessToken: string; distributedClaimAccessTokenProvider?: never }
-        | { distributedClaimAccessTokenProvider: () => string | Promise<string>; distributedClaimAccessToken?: never };
+        | { distributedClaimAccessToken?: string | undefined; distributedClaimAccessTokenProvider?: undefined }
+        | {
+            distributedClaimAccessTokenProvider?: (() => string | Promise<string>) | undefined;
+            distributedClaimAccessToken?: undefined;
+        };
 
     type JwtAuthConfig = JwtAuthConfigCommon &
         (

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-vault-client",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "description": "A Vault Client implemented in pure javascript for HashiCorp Vault. It supports variety of Auth Backends and performs lease renewal for issued auth token.",
   "repository": {
     "url": "git+https://github.com/namecheap/node-vault-client.git"
@@ -21,6 +21,7 @@
     "test:e2e": "mocha --exit \"test/e2e/e2e.test.mjs\"",
     "test:e2e:kv2": "mocha --exit \"test/e2e/e2e.kv2.test.mjs\"",
     "test:e2e:jwt": "mocha --exit \"test/e2e/e2e.jwt.test.mjs\"",
+    "test:e2e:generic": "mocha --exit \"test/e2e/e2e.generic.test.mjs\"",
     "test:example": "node examples/jwt-auth/vault-jwt-demo.mjs",
     "coverage": "c8 npm run test:unit",
     "lint": "eslint src/ test/ examples/",
@@ -54,10 +55,11 @@
   },
   "overrides": {
     "serialize-javascript": "^7.1.4",
-    "glob": "^13.0.0",
+    "glob": "^14.0.3",
     "diff": "^8.0.3",
     "brace-expansion": "^5.0.12",
-    "js-yaml": "^4.3.2"
+    "js-yaml": "^4.3.2",
+    "minimatch": "^11.0.4"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/src/VaultApiClient.js

@@ -1,8 +1,86 @@
 'use strict';
 
+const { defaultMaxListeners, getMaxListeners, setMaxListeners } = require('events');
 const errors = require('./errors');
 const { trimTrailingSlashes } = require('./slashes');
 
+// Above Vault's own default max_request_duration (90 s), so no request a default-configured
+// Vault would still answer is cut short, and below the 300 s headers/body timeouts of the
+// dispatcher Node's fetch() uses by default.
+const DEFAULT_TIMEOUT_MS = 120000;
+// setTimeout() fires after 1 ms for a delay that does not fit in a signed 32-bit integer.
+const MAX_TIMEOUT_MS = 2147483647;
+// The listener limit fetch() gives a signal it is passed (see deadline()).
+const FETCH_MAX_LISTENERS = 1500;
+
+function validateTimeout(timeout) {
+    // null reads as "not set", as it does in a config file.
+    if (timeout === undefined || timeout === null) {
+        return DEFAULT_TIMEOUT_MS;
+    }
+    if (!Number.isInteger(timeout) || timeout < 0 || timeout > MAX_TIMEOUT_MS) {
+        throw new errors.InvalidArgumentsError(
+            `"api.timeout" should be an integer number of milliseconds from 0 to ${MAX_TIMEOUT_MS}, ` +
+            `got ${String(timeout)}`
+        );
+    }
+    return timeout;
+}
+
+/**
+ * What fetch() accepts as a signal: Node 20 and 22 take any object with a boolean `aborted`
+ * and an `addEventListener` (an abort-controller polyfill, a signal from another realm).
+ */
+function isSignalLike(value) {
+    return value !== null && typeof value === 'object'
+        && typeof value.aborted === 'boolean' && typeof value.addEventListener === 'function';
+}
+
+/**
+ * A per-request deadline. A plain timer, cleared once the request settles, rather than
+ * AbortSignal.timeout(), whose timer cannot be cancelled and so outlives every fast request.
+ * A `requestOptions.signal` still aborts the request: it is followed through a listener that
+ * is removed at the same point, since that signal lives as long as the client.
+ *
+ * @param {number} ms
+ * @param {AbortSignal} [signal] - `requestOptions.signal`
+ * @returns {{signal: AbortSignal, isTimeout: function(*): boolean, clear: function(): void}}
+ */
+function deadline(ms, signal) {
+    const controller = new AbortController();
+    const reason = new DOMException('The operation was aborted due to timeout', 'TimeoutError');
+    const timer = setTimeout(() => controller.abort(reason), ms);
+    const follow = () => controller.abort(signal.reason);
+    if (signal) {
+        if (signal.aborted) {
+            follow();
+        } else {
+            // fetch() raised a signal's listener limit to 1500 when it was still at the default;
+            // it now gets the client's own signal, so do the same here, or more than ten
+            // requests in flight on one signal print MaxListenersExceededWarning (Node 20).
+            try {
+                if (getMaxListeners(signal) === defaultMaxListeners) {
+                    setMaxListeners(FETCH_MAX_LISTENERS, signal);
+                }
+            } catch {
+                // not an EventTarget (a polyfill): it has no listener limit to raise
+            }
+            signal.addEventListener('abort', follow, { once: true });
+        }
+    }
+
+    return {
+        signal: controller.signal,
+        isTimeout: (err) => err === reason,
+        clear: () => {
+            clearTimeout(timer);
+            if (signal && typeof signal.removeEventListener === 'function') {
+                signal.removeEventListener('abort', follow);
+            }
+        },
+    };
+}
+
 /**
  * Joins URL segments with single slashes while preserving the leading
  * protocol (e.g. "https://"). Replaces the former `url-join` dependency.
@@ -35,6 +113,9 @@ class VaultApiClient {
      *      (`method`, `body`) always take precedence; `headers` are merged with the
      *      per-request headers winning. Stored by reference (not deep-cloned) so live
      *      objects such as a Dispatcher keep their prototype and remain usable.
+     * @param {number} [config.timeout=120000] - milliseconds a request may take, response
+     *      headers, body and redirects included, before it rejects with
+     *      {@link RequestTimeoutError}. `0` turns the limit off; `null` gives the default.
      * @param {Object} logger
      * @param {String} [namespace] - Vault namespace. When set, `X-Vault-Namespace` is added to
      *      every request (login, token lookup/renewal, and secret operations) so namespacing is
@@ -55,6 +136,12 @@ class VaultApiClient {
             this.__config.requestOptions = requestOptions;
         }
 
+        this.__timeout = validateTimeout(this.__config.timeout);
+        // 3.0.x ignored an api.timeout key, so a config may still carry one written in seconds.
+        if (this.__timeout > 0 && this.__timeout < 1000) {
+            logger.warn('"api.timeout" is %d ms; it is in milliseconds, not seconds', this.__timeout);
+        }
+
         this.__namespace = namespace !== undefined ? namespace : this.__config.namespace;
         this._logger = logger;
     }
@@ -102,7 +189,28 @@ class VaultApiClient {
             uri
         );
 
-        return fetch(uri, options).then((response) => {
+        // A requestOptions.signal that fetch() would reject is passed on untouched, without the
+        // deadline, so fetch() rejects it as it always has. The deadline is armed last, and
+        // cleared if fetch() throws synchronously, so no timer outlives a failed call.
+        const userSignal = requestOptions.signal;
+        const limit = this.__timeout > 0 && (userSignal === undefined || userSignal === null
+            || isSignalLike(userSignal))
+            ? deadline(this.__timeout, userSignal || undefined)
+            : null;
+        let pending;
+        if (limit === null) {
+            pending = fetch(uri, options);
+        } else {
+            options.signal = limit.signal;
+            try {
+                pending = fetch(uri, options);
+            } catch (err) {
+                limit.clear();
+                throw err;
+            }
+        }
+
+        const request = pending.then((response) => {
             return response.text().then((text) => {
                 let body;
                 if (text) {
@@ -127,6 +235,18 @@ class VaultApiClient {
                 return body;
             });
         });
+        if (limit === null) {
+            return request;
+        }
+
+        return request
+            .catch((err) => {
+                if (limit.isTimeout(err)) {
+                    throw new errors.RequestTimeoutError(this.__timeout, { cause: err });
+                }
+                throw err;
+            })
+            .finally(limit.clear);
     }
 }
 

package/src/VaultClient.js

@@ -18,24 +18,84 @@ const { trimTrailingSlashes } = require('./slashes');
 const noop = () => {};
 const vaultInstances = {};
 
+// Functions, and objects that are not plain data (an undici dispatcher, a logger class
+// instance), compare by identity. Their own enumerable keys say nothing about what they do:
+// structurally, any two dispatchers look alike, and so do two loggers built from different
+// functions, so a boot() that passed a different one was ignored without a warning (#224).
+// A Buffer, Date, URL or RegExp compares by value, so an equal one re-created per call still
+// matches. No user code (getters, toJSON, Proxy traps) decides the comparison.
+//
+// Per-process ids, in a WeakMap so that fingerprinting never keeps an option (or the closure
+// state it captures) alive.
+const identityIds = new WeakMap();
+let nextIdentityId = 0;
+
+function identityId(value) {
+    if (!identityIds.has(value)) {
+        identityIds.set(value, ++nextIdentityId);
+    }
+    return identityIds.get(value);
+}
+
+/**
+ * How an object takes part in the fingerprint: 'array' and 'plain' by content, 'value' by
+ * {@link valueOf}, anything else by identity. Plain includes a null prototype and an
+ * Object.prototype from another realm (vm, a test runner's structuredClone). A Proxy whose
+ * traps throw compares by identity rather than making boot() throw.
+ */
+function kindOf(value) {
+    try {
+        if (Array.isArray(value)) {
+            return 'array';
+        }
+        if (Buffer.isBuffer(value) || value instanceof Date || value instanceof URL || value instanceof RegExp) {
+            return 'value';
+        }
+        const proto = Object.getPrototypeOf(value);
+        return proto === null || Object.getPrototypeOf(proto) === null ? 'plain' : 'identity';
+    } catch {
+        return 'identity';
+    }
+}
+
+function valueOf(value) {
+    if (Buffer.isBuffer(value)) {
+        return `buffer:${value.toString('base64')}`;
+    }
+    if (value instanceof Date) {
+        return `date:${value.getTime()}`;
+    }
+    return `${value instanceof URL ? 'url' : 'regexp'}:${JSON.stringify(String(value))}`;
+}
+
 /**
- * Order-insensitive canonical form of the boot options, hashed so that no credential is
- * retained just to compare two boot() calls. Functions compare by identity, which is what
- * a caller passing `jwtProvider` expects.
+ * Order-insensitive canonical form of a boot option, hashed so that no credential is retained
+ * just to compare two boot() calls. Plain objects and arrays compare by content, functions and
+ * other objects by identity, and a Buffer, Date, URL or RegExp by value.
  */
 function fingerprintOptions(value, seen) {
     if (typeof value === 'function') {
-        return 'fn';
+        return `fn#${identityId(value)}`;
+    }
+    if (typeof value === 'bigint') {
+        return `${value}n`;
     }
     if (value === null || typeof value !== 'object') {
         return JSON.stringify(value) || String(value);
     }
+    const kind = kindOf(value);
+    if (kind === 'value') {
+        return valueOf(value);
+    }
+    if (kind === 'identity') {
+        return `obj#${identityId(value)}`;
+    }
     seen = seen || new Set();
     if (seen.has(value)) {
         return 'circular';
     }
     seen.add(value);
-    if (Array.isArray(value)) {
+    if (kind === 'array') {
         return `[${value.map((item) => fingerprintOptions(item, seen)).join(',')}]`;
     }
     const body = Object.keys(value).sort()
@@ -44,8 +104,19 @@ function fingerprintOptions(value, seen) {
     return `{${body}}`;
 }
 
-function optionsDigest(options) {
-    return crypto.createHash('sha256').update(fingerprintOptions(options)).digest('hex');
+/** One digest per top-level option, so a mismatch can name the options that differ. */
+function optionsDigests(options) {
+    const digests = new Map();
+    for (const key of Object.keys(options)) {
+        digests.set(key, crypto.createHash('sha256').update(fingerprintOptions(options[key])).digest('hex'));
+    }
+    return digests;
+}
+
+/** The top-level options whose digests differ, sorted; empty when the options match. */
+function differingOptions(before, after) {
+    const keys = new Set([...before.keys(), ...after.keys()]);
+    return [...keys].filter((key) => before.get(key) !== after.get(key)).sort();
 }
 
 // fetch() parses the joined URL per the WHATWG URL Standard: '?' starts the query, '#' the
@@ -128,6 +199,9 @@ class VaultClient {
      * @param {Object} [options.api.requestOptions] - extra options merged into every HTTP
      *      request (e.g. an undici `dispatcher` for a proxy/SOCKS agent or custom TLS/CA trust).
      *      See {@link VaultApiClient#constructor}.
+     * @param {number} [options.api.timeout=120000] - milliseconds a request may take, response
+     *      headers, body and redirects included, before it rejects with RequestTimeoutError.
+     *      `0` turns the limit off.
      * @param {Object} [options.api.kv] - KV engine options
      * @param {boolean} [options.api.kv.autoDetect=false] - When true, auto-detect KV version per mount
      * @param {Object} [options.api.engines] - Mount-to-version overrides, e.g. { secret: 2, legacy: 1 }
@@ -210,8 +284,15 @@ class VaultClient {
      * `options` are used only when the instance is first created. A later call for a name
      * that already exists returns the existing instance and ignores the options it was
      * given; when those options differ from the ones the instance was booted with, that is
-     * logged as a warning rather than passing silently. Use {@link VaultClient.get} to
-     * fetch an existing instance, or {@link VaultClient.clear} to replace one.
+     * logged as a warning, naming the top-level options that differ, rather than passing
+     * silently. The warning is logged once per instance for each set of differing options.
+     * Use {@link VaultClient.get} to fetch an existing instance, or {@link VaultClient.clear}
+     * to replace one.
+     *
+     * Options are compared as hashes, so no credential is kept for the comparison. Plain
+     * objects and arrays compare by content, in any key order. Functions and other objects (a
+     * logger class instance, an undici dispatcher) compare by identity, and a Buffer, Date,
+     * URL or RegExp by value.
      *
      * @param {String} name - Vault instance name
      * @param {Object} options - options for {@link VaultClient#constructor}. Required on
@@ -226,14 +307,22 @@ class VaultClient {
         let instance = vaultInstances[name];
         if (instance === undefined) {
             vaultInstances[name] = instance = new VaultClient(options);
-            instance.__bootDigest = optionsDigest(options);
-        } else if (instance.__bootDigest !== optionsDigest(options)) {
+            instance.__bootDigests = optionsDigests(options);
+            instance.__bootWarned = new Set();
+            return instance;
+        }
+
+        // Once per instance for each set of differing options: code that re-creates its logger
+        // for every boot() call would otherwise log this on every call.
+        const differing = differingOptions(instance.__bootDigests, optionsDigests(options)).join(', ');
+        if (differing !== '' && !instance.__bootWarned.has(differing)) {
+            instance.__bootWarned.add(differing);
             instance.__log.warn(
                 'VaultClient.boot("%s") was called with different options than the existing ' +
                 'instance was booted with; the existing instance is returned and these options ' +
                 'are ignored. Use VaultClient.get("%s") to fetch it, or VaultClient.clear("%s") ' +
-                'first to replace it.',
-                name, name, name
+                'first to replace it. Differing options: %s.',
+                name, name, name, differing
             );
         }
         return instance;

package/src/auth/VaultBaseAuth.js

@@ -9,8 +9,6 @@ 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');
 
@@ -50,35 +48,40 @@ function tokenExpiryMilliseconds(authToken) {
 }
 
 /**
- * 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}
+ * True when Vault says it granted less than the requested lifetime because the token reached a
+ * maximum TTL (its explicit max TTL, the role's `token_max_ttl` or the mount's max lease TTL).
+ * Vault reports this on every capped renew-self as a warning such as
+ * `TTL of "10s" exceeded the effective max_ttl of "9s"; TTL value is capped accordingly`
+ * (measured on 1.21 and 2.2) and never on an uncapped one. A capped token's deadline cannot move
+ * again, so further renewals are pointless; the next one would fail with "past the max TTL".
+ *
+ * Vault's other cap warning, `period of "4s" exceeded the effective max_ttl of "2s"; period value
+ * is capped accordingly`, must NOT match: it is sent on every renewal of a periodic token whose
+ * period exceeds the role's `token_max_ttl` or the mount's max lease TTL, and that token stays
+ * renewable indefinitely at the shorter period (measured on 2.2).
+ *
+ * `lease_duration < increment` is not a usable substitute: periodic tokens ignore the increment.
+ *
+ * @param {Object|null|undefined} renewResponse - renew-self response body
+ * @returns {boolean}
  * @private
  */
-function tokenUnadjustedExpiryMilliseconds(authToken) {
-    if (typeof authToken.getUnadjustedExpiresAtMilliseconds === 'function') {
-        const expiry = authToken.getUnadjustedExpiresAtMilliseconds();
-        if (Number.isFinite(expiry)) {
-            return expiry;
-        }
-    }
-
-    return tokenExpiryMilliseconds(authToken);
+function renewalCappedByMaxTtl(renewResponse) {
+    const warnings = renewResponse && Array.isArray(renewResponse.warnings) ? renewResponse.warnings : [];
+    return warnings.some((warning) => typeof warning === 'string'
+        && /max_?ttl/i.test(warning) && /\bTTL value is capped\b/i.test(warning));
 }
 
 /**
- * Read Vault's whole-second TTL when the token implementation exposes it.
- * @param {AuthToken} authToken
- * @returns {number|null}
+ * ISO form of a millisecond timestamp, or its plain string form when Date cannot represent it,
+ * so that a log line about a duck-typed token never throws a RangeError.
+ * @param {number} ms
+ * @returns {string}
  * @private
  */
-function tokenTtlSeconds(authToken) {
-    if (typeof authToken.getTtlSeconds !== 'function') {
-        return null;
-    }
-    const ttl = authToken.getTtlSeconds();
-    return typeof ttl === 'number' && Number.isFinite(ttl) ? ttl : null;
+function formatTimestamp(ms) {
+    const date = new Date(ms);
+    return Number.isNaN(date.getTime()) ? String(ms) : date.toISOString();
 }
 
 /**
@@ -101,7 +104,7 @@ function warnRenewalStopped(auth, authToken, reason) {
         'token renewal stopped (accessor=%s): %s; client-side expiry is %s; %s',
         authToken.getAccessor(),
         reason,
-        expiry === null ? 'unknown' : new Date(expiry).toISOString(),
+        expiry === null ? 'unknown' : formatTimestamp(expiry),
         nextAction
     );
 }
@@ -255,16 +258,10 @@ class VaultBaseAuth {
             this.__renewalEpoch++;
 
             if (authToken.isRenewable()) {
-                // Gate the log on the flag too: the guard lives inside
-                // __setupTokenRefreshTimer, so without this the client claims it armed a
-                // timer while arming nothing -- the one diagnostic an operator reads when a
-                // `renewal: false` process still hangs.
-                if (this.__renewalEnabled) {
-                    this._log.debug(
-                        'setting refresh timer for token (accessor=%s)',
-                        authToken.getAccessor()
-                    );
-                } else {
+                // __setupTokenRefreshTimer logs once it has actually armed a timer, and warns
+                // when it cannot; this covers the remaining case, the one diagnostic an operator
+                // reads when a `renewal: false` process still hangs.
+                if (!this.__renewalEnabled) {
                     this._log.debug(
                         'renewal disabled by config; not arming a refresh timer (accessor=%s)',
                         authToken.getAccessor()
@@ -371,7 +368,6 @@ 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()) {
@@ -379,47 +375,20 @@ class VaultBaseAuth {
             }
             this.__refreshTimeout = null;
 
-            this.__renewToken(authToken).then(renewedToken => {
+            // Two handlers, not .then().catch(): once the renewed token is adopted, a failure
+            // in the bookkeeping below must not be mistaken for a failed renewal and re-arm a
+            // timer against the token this client no longer holds.
+            this.__renewToken(authToken).then(({ renewedToken, cappedByMaxTtl }) => {
                 if (superseded()) {
                     return;
                 }
                 this.__authToken = renewedToken;
-                if (!renewedToken.isRenewable() || renewedToken.isExpired()) {
-                    this.__setupTokenRefreshTimer(renewedToken);
+                if (cappedByMaxTtl) {
+                    warnRenewalStopped(this, renewedToken, 'Vault capped the renewal at the token\'s maximum TTL');
                     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 => {
+                this.__setupTokenRefreshTimer(renewedToken);
+            }, err => {
                 if (superseded()) {
                     return;
                 }
@@ -433,18 +402,27 @@ class VaultBaseAuth {
                 } else {
                     this._log.error(message, err);
                 }
+            }).catch(err => {
+                // Only a throwing logger (or a broken duck-typed token) gets here. Report it if
+                // the logger allows, and never let it surface as an unhandled rejection.
+                try {
+                    this._log.error('token renewal bookkeeping failed: %s', safeMessage(err));
+                } catch {
+                    // nothing left to report to
+                }
             });
         }, timer);
 
         this._log.debug(
-            'sleeping for %s',
+            'renewal timer armed (accessor=%s); renewing in %s',
+            authToken.getAccessor(),
             humanizeMs(timer)
         );
     }
 
     /**
      * @param {AuthToken} authToken
-     * @returns {Promise.<AuthToken>}
+     * @returns {Promise.<{renewedToken: AuthToken, cappedByMaxTtl: boolean}>}
      * @private
      */
     __renewToken(authToken) {
@@ -454,9 +432,11 @@ class VaultBaseAuth {
         const data = this.__renewalIncrement === undefined ? null : {increment: this.__renewalIncrement};
 
         return this.__apiClient.makeRequest('POST', '/auth/token/renew-self', data, {'X-Vault-Token': authToken.getId()})
-            .then(() => {
+            .then((renewResponse) => {
                 this._log.info('successfully renewed token');
-                return this._getTokenEntity(authToken.getId());
+                const cappedByMaxTtl = renewalCappedByMaxTtl(renewResponse);
+                return this._getTokenEntity(authToken.getId())
+                    .then((renewedToken) => ({ renewedToken, cappedByMaxTtl }));
             })
             .catch((reason) => {
                 this._log.error('token renew failed: %s', safeMessage(reason));

package/src/auth/VaultJwtAuth.js

@@ -3,10 +3,31 @@
 const fs = require('fs');
 const VaultBaseAuth = require('./VaultBaseAuth');
 const errors = require('../errors');
+const safeMessage = require('../safeMessage');
 
 const JWT_SOURCE_KEYS = ['jwt', 'jwtPath', 'jwtProvider'];
 
+/**
+ * Normalizes an optional access token: surrounding whitespace (a trailing newline from a file or
+ * an env var) is dropped, and anything that is not a non-empty string afterwards is `undefined`.
+ *
+ * @param {*} value
+ * @returns {String|undefined}
+ */
+function normalizeAccessToken(value) {
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+
 class VaultJwtAuth extends VaultBaseAuth {
+    // Private fields rather than `__` properties: util.inspect / console.log / JSON.stringify of
+    // the client never show them, so neither credential leaks through a logged object.
+    #jwt;
+    #distributedClaimAccessToken;
+
     /**
      * @param {VaultApiClient} apiClient - see {@link VaultBaseAuth#constructor}
      * @param {Object} logger
@@ -21,14 +42,17 @@ class VaultJwtAuth extends VaultBaseAuth {
      *   returning `string | Promise<string>`. Called fresh on every login (never at construction
      *   or cached across logins) so it can mint a short-lived token -- the shape GitHub Actions'
      *   `core.getIDToken()`, cloud metadata endpoints and SPIFFE workloads need.
-     * @param {String} [config.distributedClaimAccessToken] - A literal OAuth access token forwarded
-     *   to Vault as `distributed_claim_access_token`. Azure/Entra roles with `fetch_groups` enabled
-     *   need it so Vault can resolve the distributed group-membership claim against the Microsoft
-     *   Graph API. Optional, and mutually exclusive with `distributedClaimAccessTokenProvider`.
+     * @param {String} [config.distributedClaimAccessToken] - A literal Microsoft Graph access token
+     *   forwarded to Vault as `distributed_claim_access_token`. Only the Azure (Entra ID) provider
+     *   uses it: when the role sets `groups_claim` and Vault has to fetch group membership from
+     *   Graph (Azure sent distributed claims, or the mount's `provider_config` sets
+     *   `fetch_groups`). Fixed at construction, so every re-login replays it; prefer the provider
+     *   in a long-running process. `undefined` means "not sent"; any other value must be a
+     *   non-empty string. Mutually exclusive with `distributedClaimAccessTokenProvider`.
      * @param {Function} [config.distributedClaimAccessTokenProvider] - (optionally async) function
      *   invoked at login time, returning `string | Promise<string>`. Called fresh on every login
-     *   (never at construction or cached across logins) because Graph access tokens are short-lived
-     *   and are usually acquired next to the JWT itself. Mutually exclusive with
+     *   (never at construction or cached across logins) because Graph access tokens are short-lived.
+     *   It runs concurrently with the JWT source. Mutually exclusive with
      *   `distributedClaimAccessToken`.
      * @param {String} [config.namespace] - Optional. Vault namespace. Applied as the X-Vault-Namespace
      *   header to every request by {@link VaultApiClient}; see {@link VaultClient#constructor}.
@@ -53,6 +77,14 @@ class VaultJwtAuth extends VaultBaseAuth {
                 + ' should be provided for VaultJwtAuth'
             );
         }
+        // An empty or non-string literal would be sent as-is and fail later, at Vault's
+        // group-fetch step, with an error that does not mention this option.
+        if (config.distributedClaimAccessToken !== undefined
+            && normalizeAccessToken(config.distributedClaimAccessToken) === undefined) {
+            throw new errors.InvalidArgumentsError(
+                '"distributedClaimAccessToken" should be a non-empty string for VaultJwtAuth'
+            );
+        }
         if (config.distributedClaimAccessTokenProvider !== undefined
             && typeof config.distributedClaimAccessTokenProvider !== 'function') {
             throw new errors.InvalidArgumentsError(
@@ -61,94 +93,124 @@ class VaultJwtAuth extends VaultBaseAuth {
         }
 
         this.__role = config.role;
-        this.__jwt = config.jwt;
+        this.#jwt = config.jwt;
         this.__jwtPath = config.jwtPath;
         this.__jwtProvider = config.jwtProvider;
-        this.__distributedClaimAccessToken = config.distributedClaimAccessToken;
+        this.#distributedClaimAccessToken = normalizeAccessToken(config.distributedClaimAccessToken);
         this.__distributedClaimAccessTokenProvider = config.distributedClaimAccessTokenProvider;
     }
 
     _authenticate() {
-        return Promise.resolve()
-            .then(() => this.__acquireJwt())
-            .then(({ jwt, source }) => Promise.resolve()
-                .then(() => this.__acquireDistributedClaimAccessToken())
-                .then((distributedClaim) => {
-                    this._log.info(
-                        'making authentication request: Vault role: "%s"; JWT source: %s (%d bytes)%s',
-                        this.__role !== undefined ? this.__role : '(default_role)', source, jwt.length,
-                        distributedClaim === undefined
-                            ? ''
-                            : `; distributed claim access token: ${distributedClaim.source}`
-                    );
-
-                    const body = { jwt };
-                    if (this.__role !== undefined) {
-                        body.role = this.__role;
-                    }
-                    if (distributedClaim !== undefined) {
-                        body.distributed_claim_access_token = distributedClaim.accessToken;
-                    }
-
-                    return this.__apiClient.makeRequest('POST', `/auth/${this._mount}/login`, body)
-                        .then((res) => {
-                            this._log.debug('received Vault client token from JWT login');
-
-                            return this._getTokenEntity(res.auth.client_token);
-                        });
-                }));
+        // Both credentials are independent and usually network-bound (IdP, IMDS, MSAL), so they
+        // are acquired concurrently: login latency is the slower of the two rather than their
+        // sum, and the JWT does not age while the Graph token is fetched.
+        //
+        // A failed JWT source rejects the login at once, as it did when the two ran in turn, so a
+        // Graph provider that hangs cannot hold up that error. A failed access token instead waits
+        // for the JWT source, so the JWT source's error is the one raised whenever both fail. The
+        // Graph provider is not cancelled: if it fails after the login already rejected, its
+        // failure is still logged, and its rejection is handled here.
+        const jwtPromise = this.__acquireJwt();
+        const claimPromise = this.__acquireDistributedClaimAccessToken()
+            .catch((claimErr) => jwtPromise.then(() => { throw claimErr; }));
+
+        return Promise.all([jwtPromise, claimPromise])
+            .then(([{ jwt, source }, distributedClaim]) => {
+                this._log.info(
+                    'making authentication request: Vault role: "%s"; JWT source: %s (%d bytes);'
+                    + ' distributed claim access token: %s',
+                    this.__role !== undefined ? this.__role : '(default_role)', source, jwt.length,
+                    distributedClaim === undefined ? 'none' : distributedClaim.source
+                );
+
+                const body = { jwt };
+                if (this.__role !== undefined) {
+                    body.role = this.__role;
+                }
+                if (distributedClaim !== undefined) {
+                    body.distributed_claim_access_token = distributedClaim.accessToken;
+                }
+
+                return this.__apiClient.makeRequest('POST', `/auth/${this._mount}/login`, body);
+            })
+            .then((res) => {
+                this._log.debug('received Vault client token from JWT login');
+
+                return this._getTokenEntity(res.auth.client_token);
+            });
     }
 
     /**
-     * @returns {{jwt: String, source: String}|Promise<{jwt: String, source: String}>}
+     * @returns {Promise<{jwt: String, source: String}>}
      * @private
      */
     __acquireJwt() {
-        if (this.__jwt !== undefined) {
-            return { jwt: this.__jwt, source: 'literal' };
+        if (this.#jwt !== undefined) {
+            return Promise.resolve({ jwt: this.#jwt, source: 'literal' });
         }
         if (this.__jwtPath !== undefined) {
-            return { jwt: fs.readFileSync(this.__jwtPath).toString(), source: 'file' };
+            return Promise.resolve()
+                .then(() => ({ jwt: fs.readFileSync(this.__jwtPath).toString(), source: 'file' }));
         }
 
-        // Wrapping in Promise.resolve().then() normalizes both a sync provider (plain return)
-        // and a synchronous throw into the same rejection path as an async one.
-        return Promise.resolve().then(() => this.__jwtProvider()).then((jwt) => {
-            if (typeof jwt !== 'string' || jwt.length === 0) {
-                throw new errors.InvalidArgumentsError(
-                    '"jwtProvider" must resolve to a non-empty JWT string'
-                );
-            }
-            return { jwt, source: 'provider' };
-        });
+        return this.__callStringProvider(this.__jwtProvider, 'jwtProvider', 'JWT')
+            .then((jwt) => ({ jwt, source: 'provider' }));
     }
 
     /**
      * Resolves to `undefined` when neither option is configured, so that the login body stays
      * byte-identical to what it was before this option existed.
      *
-     * @returns {undefined|{accessToken: String, source: String}|Promise<{accessToken: String, source: String}>}
+     * @returns {Promise<undefined|{accessToken: String, source: String}>}
      * @private
      */
     __acquireDistributedClaimAccessToken() {
-        if (this.__distributedClaimAccessToken !== undefined) {
-            return { accessToken: this.__distributedClaimAccessToken, source: 'literal' };
+        if (this.#distributedClaimAccessToken !== undefined) {
+            return Promise.resolve({ accessToken: this.#distributedClaimAccessToken, source: 'literal' });
         }
         if (this.__distributedClaimAccessTokenProvider === undefined) {
-            return undefined;
+            return Promise.resolve(undefined);
         }
 
-        // Wrapping in Promise.resolve().then() normalizes both a sync provider (plain return)
-        // and a synchronous throw into the same rejection path as an async one.
-        return Promise.resolve().then(() => this.__distributedClaimAccessTokenProvider()).then((accessToken) => {
-            if (typeof accessToken !== 'string' || accessToken.length === 0) {
+        return this.__callStringProvider(
+            this.__distributedClaimAccessTokenProvider, 'distributedClaimAccessTokenProvider', 'access token'
+        ).then((accessToken) => {
+            const normalized = normalizeAccessToken(accessToken);
+            if (normalized === undefined) {
                 throw new errors.InvalidArgumentsError(
                     '"distributedClaimAccessTokenProvider" must resolve to a non-empty access token string'
                 );
             }
-            return { accessToken, source: 'provider' };
+            return { accessToken: normalized, source: 'provider' };
         });
     }
+
+    /**
+     * Calls a user-supplied credential provider. Wrapping in Promise.resolve().then() normalizes
+     * both a sync provider (plain return) and a synchronous throw into the same rejection path as
+     * an async one. A provider failure is rethrown unchanged, after logging which provider it was:
+     * both are often backed by the same metadata endpoint, so the bare error does not say.
+     *
+     * @param {Function} provider
+     * @param {String} name - config key, used in messages
+     * @param {String} what - what the provider resolves to, used in messages
+     * @returns {Promise<String>}
+     * @private
+     */
+    __callStringProvider(provider, name, what) {
+        return Promise.resolve().then(() => provider()).then(
+            (value) => {
+                if (typeof value !== 'string' || value.length === 0) {
+                    throw new errors.InvalidArgumentsError(`"${name}" must resolve to a non-empty ${what} string`);
+                }
+                return value;
+            },
+            (err) => {
+                this._log.error('JWT login aborted: "%s" failed: %s', name, safeMessage(err));
+                throw err;
+            }
+        );
+    }
 }
 
 module.exports = VaultJwtAuth;

package/src/errors.d.ts

@@ -16,3 +16,8 @@ export declare class VaultHttpError extends VaultError {
     statusCode: number;
     error: unknown;
 }
+
+export declare class RequestTimeoutError extends VaultError {
+    constructor(timeout: number, options?: { cause?: unknown });
+    timeout: number;
+}

package/src/errors.js

@@ -41,6 +41,23 @@ class VaultHttpError extends VaultError {
     }
 }
 
+/**
+ * A request to Vault did not complete within `api.timeout` milliseconds: response headers,
+ * body and any redirects included. The `fetch()` rejection (a `TimeoutError` DOMException)
+ * is on `cause`.
+ */
+class RequestTimeoutError extends VaultError {
+    /**
+     * @param {number} timeout - the `api.timeout` that elapsed, in milliseconds. Exposed as
+     *   `error.timeout`.
+     * @param {{cause?: *}} [options]
+     */
+    constructor(timeout, options) {
+        super(`Vault request timed out after ${timeout} ms (api.timeout)`, options);
+        this.timeout = timeout;
+    }
+}
+
 module.exports = {
     VaultError,
     InvalidArgumentsError,
@@ -48,4 +65,5 @@ module.exports = {
     AuthTokenExpiredError,
     UnsupportedOperationError,
     VaultHttpError,
+    RequestTimeoutError,
 };