node-vault-client 3.0.0 → 3.0.1

package/README.md

@@ -365,19 +365,31 @@ on the next call — no background timer at all. Two reasons to want that:
 Renewal off means the token is allowed to expire, and what happens next depends on whether your
 backend can obtain a *fresh* credential unaided:
 
-| backend | on expiry with `renewal: false` |
-| --- | --- |
-| `kubernetes`, `iam`, `jwt` with `jwtPath`/`jwtProvider` | clean re-login — the JWT or AWS credential is re-acquired, so this is the intended case |
-| `appRole` | re-login **replays the same `secret_id`**. Fine for a reusable one; with Vault's recommended hardening (`secret_id_num_uses=1`, or a short `secret_id_ttl`) the second login is rejected |
-| `jwt` with a literal `jwt` | replays the same JWT, so it works only until the IdP-issued token expires |
-| `token` | **cannot re-authenticate at all.** The client raises `AuthTokenExpiredError` from then on, permanently |
+| backend | on expiry with `renewal: false` | at max TTL with renewal enabled |
+| --- | --- | --- |
+| `kubernetes`, `iam`, `jwt` with `jwtPath`/`jwtProvider` | clean re-login — the JWT or AWS credential is re-acquired, so this is the intended case | clean re-login on the next call after the client-side expiry deadline |
+| `appRole` | re-login **replays the same `secret_id`**. Fine for a reusable one; with Vault's recommended hardening (`secret_id_num_uses=1`, or a short `secret_id_ttl`) the second login is rejected | re-login replays the same `secret_id`; a single-use or expired secret is rejected |
+| `jwt` with a literal `jwt` | replays the same JWT, so it works only until the IdP-issued token expires | replays the same JWT; once it expires, login is rejected |
+| `token` | **cannot re-authenticate at all.** The client raises `AuthTokenExpiredError` from then on, permanently | **cannot re-authenticate at all.** The client raises `AuthTokenExpiredError` after the max-TTL expiry |
+
+#### Tokens that reach their maximum TTL
+
+Vault stops extending a renewable token when it reaches its maximum TTL. The client uses Vault's
+absolute `expire_time` when available, treats `ttl: 0` as expired immediately, and stops background
+renewal when successive absolute expiry deadlines do not materially advance. Because Vault reports
+whole-second TTLs, the scheduler also compares the reported TTL with the elapsed renewal interval;
+short periodic tokens keep renewing even when each expiry advance is one second or less. A
+`renewalIncrement` that meaningfully shortens the expiry still schedules from the new deadline. For positive TTLs above 60 seconds, the client keeps a one-minute
+safety margin for requests in flight; TTLs of 60 seconds or less have no margin. The next call after
+the client-side expiry deadline re-authenticates, as shown in the table above.
 
 Two consequences worth stating plainly:
 
-* For `token` auth this **is** a behaviour change, not a no-op. A renewable token handed to `token`
-  auth is renewed indefinitely today; with `renewal: false` it expires and every later call rejects
-  for the life of the process. `close()` does not reset it — recovery means
-  `VaultClient.clear(name)` and booting again.
+* **For `token` auth, there is no fresh credential for re-authentication.** With `renewal: false`,
+  an otherwise renewable token is allowed to expire without a background renewal. With renewal
+  enabled, the client stops the background loop once Vault no longer extends the expiry materially.
+  After expiry every later call rejects for the life of the process. `close()` does not reset it —
+  recovery means `VaultClient.clear(name)` and booting again.
 * For `appRole` and literal-`jwt`, a login that can no longer succeed is retried on **every**
   subsequent call, since a failed login clears the cached token. That is a failing request per
   `read()`, with no backoff. Prefer `jwtPath`/`jwtProvider`, a reusable `secret_id`, or leaving
@@ -410,8 +422,8 @@ auth: {
 Lower `renewalFraction` values renew earlier and more often, which buys headroom if Vault is briefly
 unreachable. A failed renewal is retried on the same rule against the *same* token, so the waits
 shrink geometrically as the remaining lifetime does — for a 1-hour token that is roughly 12 attempts
-at `0.5` (1800s, 900s, 450s, …) versus 27 at `0.25`, both bottoming out at a 1-second floor just
-before expiry. Higher values renew later and talk to Vault less.
+at `0.5` (1800s, 900s, 450s, …) versus 27 at `0.25`, both bottoming out at a 250 ms minimum delay
+when it still fits before expiry. Higher values renew later and talk to Vault less.
 
 `renewalIncrement` is a request, not a guarantee: Vault grants at most the token's max TTL and may
 return less. Both keys are validated at construction — a `renewalFraction` outside `(0, 1)` or a
@@ -1018,7 +1030,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

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

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

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