node-vault-client 3.0.0 → 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', {
@@ -365,19 +376,43 @@ on the next call — no background timer at all. Two reasons to want that:
 Renewal off means the token is allowed to expire, and what happens next depends on whether your
 backend can obtain a *fresh* credential unaided:
 
-| backend | on expiry with `renewal: false` |
-| --- | --- |
-| `kubernetes`, `iam`, `jwt` with `jwtPath`/`jwtProvider` | clean re-login — the JWT or AWS credential is re-acquired, so this is the intended case |
-| `appRole` | re-login **replays the same `secret_id`**. Fine for a reusable one; with Vault's recommended hardening (`secret_id_num_uses=1`, or a short `secret_id_ttl`) the second login is rejected |
-| `jwt` with a literal `jwt` | replays the same JWT, so it works only until the IdP-issued token expires |
-| `token` | **cannot re-authenticate at all.** The client raises `AuthTokenExpiredError` from then on, permanently |
+| backend | on expiry with `renewal: false` | at max TTL with renewal enabled |
+| --- | --- | --- |
+| `kubernetes`, `iam`, `jwt` with `jwtPath`/`jwtProvider` | clean re-login — the JWT or AWS credential is re-acquired, so this is the intended case | clean re-login on the next call after the client-side expiry deadline |
+| `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 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 this **is** a behaviour change, not a no-op. A renewable token handed to `token`
-  auth is renewed indefinitely today; with `renewal: false` it expires and every later call rejects
-  for the life of the process. `close()` does not reset it — recovery means
-  `VaultClient.clear(name)` and booting again.
+* **For `token` auth, there is no fresh credential for re-authentication.** With `renewal: false`,
+  an otherwise renewable token is allowed to expire without a background renewal. With renewal
+  enabled, the client stops the background loop once Vault 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**
   subsequent call, since a failed login clears the cached token. That is a failing request per
   `read()`, with no backoff. Prefer `jwtPath`/`jwtProvider`, a reusable `secret_id`, or leaving
@@ -410,11 +445,17 @@ auth: {
 Lower `renewalFraction` values renew earlier and more often, which buys headroom if Vault is briefly
 unreachable. A failed renewal is retried on the same rule against the *same* token, so the waits
 shrink geometrically as the remaining lifetime does — for a 1-hour token that is roughly 12 attempts
-at `0.5` (1800s, 900s, 450s, …) versus 27 at `0.25`, both bottoming out at a 1-second floor just
-before expiry. Higher values renew later and talk to Vault less.
+at `0.5` (1800s, 900s, 450s, …) versus 27 at `0.25`, both bottoming out at a 250 ms minimum delay
+when it still fits before expiry. Higher values renew later and talk to Vault less. 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.
 
@@ -544,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>
 
@@ -1018,7 +1063,7 @@ try {
 | `VaultHttpError` | `VaultError` | Vault answered with a non-2xx status. Carries the status as `statusCode` and the parsed body as `error`. `message` (`"<status> - <raw body text>"`) and `error` hold the full response body, which can include secret material (e.g. a partially failed transit batch), so log `statusCode` and `error.errors` rather than the error object itself. |
 | `InvalidArgumentsError` | `VaultError` | Bad arguments or configuration: `boot()` called without options, an unknown instance name passed to `get()`, an unsupported `auth.type`, invalid renewal options, an invalid node-config substitution map, or a KV method path that fails [path validation](#path-validation). |
 | `InvalidAWSCredentialsError` | `InvalidArgumentsError` | `auth.config.credentials` was supplied but is not a usable `accessKeyId` / `secretAccessKey` pair. |
-| `AuthTokenExpiredError` | `VaultError` | The Vault token expired and the backend cannot obtain a new one. `token` auth can never re-authenticate; other backends reach this only with `renewal: false` and a credential they cannot replay. |
+| `AuthTokenExpiredError` | `VaultError` | The Vault token expired and the backend cannot obtain a new one. `token` auth can never re-authenticate and reaches this error at max TTL even with renewal enabled; other backends can also reach it when re-authentication is disabled or their credential can no longer be replayed. |
 | `UnsupportedOperationError` | `VaultError` | A v2-only method (`deleteVersions`, `undeleteVersions`, `destroyVersions`, `readMetadata`, `deleteMetadata`) was called against a mount that did not resolve as KV v2. |
 
 ## Contributing

package/index.d.ts

@@ -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 &
         (
@@ -127,5 +131,6 @@ declare namespace VaultClient {
         isExpired(): boolean;
         isRenewable(): boolean;
         getExpiresAt(): number | null;
+        getTtlSeconds?(): number | null;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-vault-client",
-  "version": "3.0.0",
+  "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/AuthToken.js

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

package/src/auth/VaultBaseAuth.js

@@ -29,6 +29,86 @@ function humanizeMs(ms) {
     return `${hours}h ${totalMinutes % 60}m`;
 }
 
+/**
+ * Read precise expiry when available, preserving the public AuthToken interface fallback.
+ * @param {AuthToken} authToken
+ * @returns {number|null}
+ * @private
+ */
+function tokenExpiryMilliseconds(authToken) {
+    if (typeof authToken.getExpiresAtMilliseconds === 'function') {
+        const expiry = authToken.getExpiresAtMilliseconds();
+        if (Number.isFinite(expiry)) {
+            return expiry;
+        }
+    }
+
+    const expiry = authToken.getExpiresAt();
+    return typeof expiry === 'number' && Number.isFinite(expiry) ? expiry * 1000 : null;
+}
+
+/**
+ * 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 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));
+}
+
+/**
+ * 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 formatTimestamp(ms) {
+    const date = new Date(ms);
+    return Number.isNaN(date.getTime()) ? String(ms) : date.toISOString();
+}
+
+/**
+ * Explain why background renewal ended without exposing the token ID.
+ * @param {VaultBaseAuth} auth
+ * @param {AuthToken} authToken
+ * @param {string} reason
+ * @returns {void}
+ * @private
+ */
+function warnRenewalStopped(auth, authToken, reason) {
+    const expiry = tokenExpiryMilliseconds(authToken);
+    const nextAction = expiry === null
+        ? 'expiry is unknown; the cached token remains in use until it is replaced'
+        : auth._reauthenticationAllowed()
+            ? 'the next call after expiry will re-authenticate'
+            : 'the next call after expiry will fail with AuthTokenExpiredError';
+
+    auth._log.warn(
+        'token renewal stopped (accessor=%s): %s; client-side expiry is %s; %s',
+        authToken.getAccessor(),
+        reason,
+        expiry === null ? 'unknown' : formatTimestamp(expiry),
+        nextAction
+    );
+}
+
 class VaultBaseAuth {
 
     /**
@@ -178,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()
@@ -255,12 +329,38 @@ class VaultBaseAuth {
             this.__refreshTimeout = null;
         }
 
-        if (!this.__renewalEnabled || !authToken.isRenewable() || authToken.isExpired()) {
+        if (!this.__renewalEnabled) {
+            return;
+        }
+        if (!authToken.isRenewable() || authToken.isExpired()) {
+            warnRenewalStopped(
+                this,
+                authToken,
+                authToken.isExpired() ? 'token already expired' : 'token is not renewable'
+            );
+            return;
+        }
+
+        const expiry = tokenExpiryMilliseconds(authToken);
+        if (expiry === null) {
+            warnRenewalStopped(this, authToken, 'token has no usable expiry');
+            return;
+        }
+
+        const remaining = expiry - Date.now();
+        if (remaining <= 0) {
+            warnRenewalStopped(this, authToken, 'token already expired');
             return;
         }
 
-        const remaining = authToken.getExpiresAt() - Math.floor(Date.now() / 1000);
-        const timer = Math.max(remaining * this.__renewalFraction, 1) * 1000;
+        const timer = Math.max(
+            Math.floor(remaining * this.__renewalFraction),
+            250
+        );
+        if (timer >= remaining) {
+            warnRenewalStopped(this, authToken, 'too little lifetime left to renew');
+            return;
+        }
 
         // A renewal that is still in flight when the token is replaced or cancelled must not
         // act on what it finds when it lands: it would overwrite the newer token, or clear
@@ -273,14 +373,22 @@ class VaultBaseAuth {
             if (superseded()) {
                 return;
             }
+            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 (cappedByMaxTtl) {
+                    warnRenewalStopped(this, renewedToken, 'Vault capped the renewal at the token\'s maximum TTL');
+                    return;
+                }
                 this.__setupTokenRefreshTimer(renewedToken);
-            }).catch(err => {
+            }, err => {
                 if (superseded()) {
                     return;
                 }
@@ -294,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) {
@@ -315,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;