node-vault-client 3.0.1 → 3.0.2

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.
 
@@ -556,9 +585,13 @@ later ones with `TimeoutError`. Pass a fresh signal per call, or use the dispatc
 
 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>
 

package/index.d.ts

@@ -79,10 +79,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.0.2",
   "description": "A Vault Client implemented in pure javascript for HashiCorp Vault. It supports variety of Auth Backends and performs lease renewal for issued auth token.",
   "repository": {
     "url": "git+https://github.com/namecheap/node-vault-client.git"

package/src/VaultClient.js

@@ -18,14 +18,31 @@ const { trimTrailingSlashes } = require('./slashes');
 const noop = () => {};
 const vaultInstances = {};
 
+// Only credential providers compare by identity: a different provider means the client would
+// authenticate differently. Other functions (logger methods, an IAM `credentials` provider
+// chain) are often re-created per call with the same behaviour, so they all fingerprint alike.
+const IDENTITY_COMPARED_KEYS = new Set(['jwtProvider', 'distributedClaimAccessTokenProvider']);
+
+// Per-process ids for those providers. A WeakMap so that fingerprinting never keeps a
+// provider (or the closure state it captures) alive.
+const functionIds = new WeakMap();
+let nextFunctionId = 0;
+
+function functionId(fn) {
+    if (!functionIds.has(fn)) {
+        functionIds.set(fn, ++nextFunctionId);
+    }
+    return functionIds.get(fn);
+}
+
 /**
  * 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.
+ * retained just to compare two boot() calls. `jwtProvider` and
+ * `distributedClaimAccessTokenProvider` compare by identity; every other function is `fn`.
  */
-function fingerprintOptions(value, seen) {
+function fingerprintOptions(value, seen, key) {
     if (typeof value === 'function') {
-        return 'fn';
+        return IDENTITY_COMPARED_KEYS.has(key) ? `fn#${functionId(value)}` : 'fn';
     }
     if (value === null || typeof value !== 'object') {
         return JSON.stringify(value) || String(value);
@@ -39,7 +56,7 @@ function fingerprintOptions(value, seen) {
         return `[${value.map((item) => fingerprintOptions(item, seen)).join(',')}]`;
     }
     const body = Object.keys(value).sort()
-        .map((key) => `${JSON.stringify(key)}:${fingerprintOptions(value[key], seen)}`)
+        .map((key) => `${JSON.stringify(key)}:${fingerprintOptions(value[key], seen, key)}`)
         .join(',');
     return `{${body}}`;
 }

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;