node-vault-client 3.1.0 → 3.3.0

package/src/auth/VaultBaseAuth.js

@@ -35,6 +35,17 @@ function humanizeMs(ms) {
  * @returns {number|null}
  * @private
  */
+/**
+ * True for a token Vault marked renewable whose lookup gave nothing to schedule a renewal from
+ * (see {@link AuthToken.fromResponse}). It is not renewable, but the renewal timer still reports
+ * it, as it did while such a lookup resolved to a NaN deadline.
+ * @param {AuthToken} authToken
+ * @returns {boolean}
+ */
+function renewableWithoutExpiry(authToken) {
+    return authToken.__renewableWithoutExpiry === true;
+}
+
 function tokenExpiryMilliseconds(authToken) {
     if (typeof authToken.getExpiresAtMilliseconds === 'function') {
         const expiry = authToken.getExpiresAtMilliseconds();
@@ -138,6 +149,32 @@ class VaultBaseAuth {
         this.__pendingLogin = null;
         this.__refreshTimeout = null;
         this.__renewalEpoch = 0;
+        /**
+         * Bumped by every {@link VaultBaseAuth#cancelTokenRefresh} call (`VaultClient#close()`
+         * makes one) and by nothing else. A login compares it before and after, so a login that
+         * was in flight when the client was closed does not arm a refresh timer.
+         * @type {number}
+         */
+        this.__cancelCount = 0;
+        /**
+         * The in-flight {@link VaultBaseAuth#checkRejectedToken} lookup, shared by every
+         * request that was rejected with the same token.
+         * @type {{id: string, promise: Promise<boolean>}|null}
+         */
+        this.__rejectionCheck = null;
+        /**
+         * Whether {@link VaultBaseAuth#revokeSelfOnClose} revokes the held token on the Vault
+         * server (`auth/token/revoke-self`). Off by default; set `auth.revokeOnClose` (see
+         * {@link VaultBaseAuth#configureRenewal}).
+         * @type {boolean}
+         */
+        this.__revokeOnClose = false;
+        /**
+         * The id of the token whose revocation on close has already been started, so a
+         * repeated close() does not revoke it twice.
+         * @type {String|null}
+         */
+        this.__revokedOnCloseId = null;
     }
 
     /**
@@ -149,12 +186,15 @@ class VaultBaseAuth {
      * @param {boolean} [authConfig.renewal=true]
      * @param {number} [authConfig.renewalFraction=0.5]
      * @param {number} [authConfig.renewalIncrement]
+     * @param {boolean} [authConfig.revokeOnClose=false] - revoke the held token
+     *      (`auth/token/revoke-self`) when the client is closed
      * @returns {void}
      */
     configureRenewal(authConfig) {
         this.__renewalEnabled = VaultBaseAuth.__validateRenewal(authConfig);
         this.__renewalFraction = VaultBaseAuth.__validateFraction(authConfig);
         this.__renewalIncrement = VaultBaseAuth.__validateIncrement(authConfig);
+        this.__revokeOnClose = VaultBaseAuth.__validateRevokeOnClose(authConfig);
     }
 
     /**
@@ -180,6 +220,29 @@ class VaultBaseAuth {
         return config.renewal;
     }
 
+    /**
+     * Strict for the same reason as "renewal": node-config's `custom-environment-variables`
+     * yields strings, so a loose check would read `VAULT_REVOKE_ON_CLOSE=true` as `'true'`
+     * and silently leave revocation off -- the exact behaviour the flag exists to request.
+     *
+     * @param {Object} [authConfig]
+     * @returns {boolean}
+     * @private
+     */
+    static __validateRevokeOnClose(config) {
+        if (!config || config.revokeOnClose === undefined) {
+            return false;
+        }
+
+        if (typeof config.revokeOnClose !== 'boolean') {
+            throw new errors.InvalidArgumentsError(
+                `"revokeOnClose" should be a boolean, got ${String(config.revokeOnClose)}`
+            );
+        }
+
+        return config.revokeOnClose;
+    }
+
     /**
      * @param {Object} [authConfig]
      * @returns {number}
@@ -252,12 +315,20 @@ class VaultBaseAuth {
 
         this._log.info('getting auth token (mount=%s)', this._mount);
 
-        const pendingLogin = this._authenticate().then(authToken => {
+        // Read before _authenticate() runs: a close() from then on, even from inside it, means
+        // this login arms no refresh timer.
+        const cancelCountAtStart = this.__cancelCount;
+        // A backend that throws instead of rejecting, or returns something that is not a
+        // promise, must not throw out of every operation. The executor still calls
+        // _authenticate() synchronously, as before.
+        const authentication = new Promise((resolve) => resolve(this._authenticate()));
+
+        const pendingLogin = authentication.then(authToken => {
             this.__pendingLogin = null;
             this.__authToken = authToken;
             this.__renewalEpoch++;
 
-            if (authToken.isRenewable()) {
+            if (authToken.isRenewable() || renewableWithoutExpiry(authToken)) {
                 // __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.
@@ -267,7 +338,9 @@ class VaultBaseAuth {
                         authToken.getAccessor()
                     );
                 }
-                this.__setupTokenRefreshTimer(authToken);
+                // close() ran while this login was in flight: every check and warning runs as
+                // before, but no timer is armed to hold the event loop.
+                this.__setupTokenRefreshTimer(authToken, this.__cancelCount !== cancelCountAtStart);
             }
 
             return authToken;
@@ -293,6 +366,7 @@ class VaultBaseAuth {
      * @returns {void}
      */
     cancelTokenRefresh() {
+        this.__markClosed();
         this.__renewalEpoch++;
         if (this.__refreshTimeout !== null) {
             lt.clearTimeout(this.__refreshTimeout);
@@ -300,6 +374,162 @@ class VaultBaseAuth {
         }
     }
 
+    /**
+     * Record a close(), so a login in flight arms no refresh timer. Called by
+     * {@link VaultBaseAuth#cancelTokenRefresh} and directly by `VaultClient#close()`, so a
+     * subclass that overrides cancelTokenRefresh() without calling super keeps the behaviour.
+     * @returns {void}
+     * @private
+     */
+    __markClosed() {
+        this.__cancelCount++;
+    }
+
+    /**
+     * Revoke the held token on the Vault server (`POST auth/token/revoke-self`), when
+     * `auth.revokeOnClose` is enabled. Called by `VaultClient#close()`.
+     *
+     * The token to revoke is the one held now, or the one an in-flight login is about to
+     * produce: that login still resolves after a close(), and its token would otherwise
+     * outlive the client by its whole TTL. A login that fails issued no token. A token that
+     * was never obtained, and one whose revocation an earlier close() already started, cost
+     * nothing to leave alone.
+     *
+     * @returns {Promise<void>|null} the revocation, so a caller may await it, or `null` when
+     *      there is nothing to do: the option is off, or no token was ever obtained. The
+     *      returned promise never rejects: `VaultClient.clear()` fires it without awaiting,
+     *      and a failed revocation is logged (`revokeSelf on close failed`) with the token
+     *      left live on the Vault server instead.
+     */
+    revokeSelfOnClose() {
+        if (!this.__revokeOnClose) {
+            return null;
+        }
+        if (this.__pendingLogin === null && this.__authToken === null) {
+            // No token was ever obtained: nothing was issued, so there is nothing to revoke.
+            return null;
+        }
+
+        // The token to revoke: the one held now, or the one the in-flight login resolves
+        // with. The login's own bookkeeping (the token cache, timer decisions) has run by
+        // the time this `then` sees it.
+        const held = this.__pendingLogin !== null
+            ? this.__pendingLogin.then((authToken) => authToken, () => null)
+            : Promise.resolve(this.__authToken);
+
+        return held.then((authToken) => {
+            // An expired token is already dead server-side: revoke-self would answer 403 and log
+            // a failure claiming the token was left live.
+            if (authToken === null || authToken.isExpired() || authToken.getId() === this.__revokedOnCloseId) {
+                return;
+            }
+            const id = authToken.getId();
+            this.__revokedOnCloseId = id;
+            try {
+                this._log.info('revoking the auth token on close (accessor=%s)', authToken.getAccessor());
+            } catch {
+                // a throwing logger must not cancel the revocation
+            }
+            return this.__apiClient
+                .makeRequest('POST', '/auth/token/revoke-self', null, { 'X-Vault-Token': authToken.getId() })
+                .then(() => {
+                    // Gone server-side: do not hand it to a call that keeps using the client.
+                    if (this.__authToken === authToken) {
+                        this.__authToken = null;
+                    }
+                }, (err) => {
+                    // Still live: let a later close() try again.
+                    if (this.__revokedOnCloseId === id) {
+                        this.__revokedOnCloseId = null;
+                    }
+                    try {
+                        this._log.error(
+                            'revokeSelf on close failed (accessor=%s): %s',
+                            authToken.getAccessor(), safeMessage(err)
+                        );
+                    } catch {
+                        // a throwing logger changes nothing: the failure is already lost to the caller
+                    }
+                });
+        });
+    }
+
+    /**
+     * Called by VaultClient after Vault answered 403 to a request made with `authToken`.
+     * Vault answers 403 both to a token it no longer accepts (revoked, or expired before the
+     * local clock says so) and to a policy that denies the request. `lookup-self`, which every
+     * login here already makes, tells the two apart, so a policy denial costs no login. A dead
+     * token is dropped, and its renewal timer cancelled, so the next getAuthToken() logs in.
+     *
+     * @param {AuthToken} authToken - the token the rejected request carried
+     * @returns {Promise<boolean>} true when the request may succeed if sent once more with
+     *      the token getAuthToken() now gives: the token was dead and has been dropped, or it
+     *      had been replaced already
+     */
+    checkRejectedToken(authToken) {
+        if (!this._reauthenticationAllowed()) {
+            return Promise.resolve(false);
+        }
+        const id = authToken.getId();
+        if (id === this.__revokedOnCloseId) {
+            // close() revoked this token on purpose (auth.revokeOnClose): a request still in
+            // flight that it rejects must not log in again after close() and leave a new,
+            // unrevoked token behind.
+            return Promise.resolve(false);
+        }
+        if (this.__authToken === null || this.__authToken.getId() !== id) {
+            return Promise.resolve(true);
+        }
+        if (this.__rejectionCheck !== null && this.__rejectionCheck.id === id) {
+            return this.__rejectionCheck.promise;
+        }
+
+        const check = {
+            id,
+            promise: this.__apiClient.makeRequest('GET', '/auth/token/lookup-self', null, {'X-Vault-Token': id})
+                .then(() => false, err => {
+                    if (err instanceof errors.VaultHttpError && err.statusCode === 403) {
+                        return true;
+                    }
+                    // Neither answer: the 403 is returned as it is, so say why no login follows.
+                    try {
+                        this._log.debug(
+                            'token rejection check inconclusive (accessor=%s): %s; returning the 403',
+                            authToken.getAccessor(), safeMessage(err)
+                        );
+                    } catch {
+                        // a throwing logger changes nothing here
+                    }
+                    return false;
+                })
+                .then(dead => {
+                    if (this.__rejectionCheck === check) {
+                        this.__rejectionCheck = null;
+                    }
+                    if (dead && this.__authToken !== null && this.__authToken.getId() === id) {
+                        this.__authToken = null;
+                        // As before, through the public method, so an override still hears of it.
+                        // Dropping a dead token is not a close(): the next login's token must be
+                        // renewed, so the close count is put back.
+                        const cancelCount = this.__cancelCount;
+                        this.cancelTokenRefresh();
+                        this.__cancelCount = cancelCount;
+                        try {
+                            this._log.warn(
+                                'Vault no longer accepts the token (accessor=%s); logging in again',
+                                authToken.getAccessor()
+                            );
+                        } catch {
+                            // a throwing logger must not keep the dead token in use
+                        }
+                    }
+                    return dead;
+                }),
+        };
+        this.__rejectionCheck = check;
+        return check.promise;
+    }
+
     /**
      * @protected
      * @returns {Promise<AuthToken>}
@@ -321,9 +551,11 @@ class VaultBaseAuth {
 
     /**
      * @param {AuthToken} authToken
+     * @param {boolean} [closedDuringLogin=false] - close() ran while the login that brought
+     *      `authToken` was in flight: check and warn as usual, but arm no timer
      * @private
      */
-    __setupTokenRefreshTimer(authToken) {
+    __setupTokenRefreshTimer(authToken, closedDuringLogin = false) {
         if (this.__refreshTimeout !== null) {
             lt.clearTimeout(this.__refreshTimeout);
             this.__refreshTimeout = null;
@@ -333,11 +565,13 @@ class VaultBaseAuth {
             return;
         }
         if (!authToken.isRenewable() || authToken.isExpired()) {
-            warnRenewalStopped(
-                this,
-                authToken,
-                authToken.isExpired() ? 'token already expired' : 'token is not renewable'
-            );
+            let reason = 'token is not renewable';
+            if (authToken.isExpired()) {
+                reason = 'token already expired';
+            } else if (renewableWithoutExpiry(authToken)) {
+                reason = 'token has no usable expiry';
+            }
+            warnRenewalStopped(this, authToken, reason);
             return;
         }
 
@@ -362,6 +596,19 @@ class VaultBaseAuth {
             return;
         }
 
+        if (closedDuringLogin) {
+            // The token is cached and returned as after any close(); nothing holds the loop.
+            try {
+                this._log.debug(
+                    'client closed during login; not arming a refresh timer (accessor=%s)',
+                    authToken.getAccessor()
+                );
+            } catch {
+                // a throwing logger must not fail a login that succeeded
+            }
+            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
         // the newer token's timer and then bail on its own expired one, leaving a live token

package/src/auth/VaultIAMAuth.js

@@ -4,6 +4,23 @@ const VaultBaseAuth = require('./VaultBaseAuth');
 const aws4 = require('aws4');
 const { fromNodeProviderChain } = require('@aws-sdk/credential-providers');
 const errors = require('../errors');
+const warnOnce = require('../warnOnce');
+
+/**
+ * The Vault server part of the warning key: origin and path of `api.url`, so spellings such as a
+ * trailing slash or an upper-case host name the same server. An unparsable value is used as is.
+ * @param {*} url
+ * @returns {string}
+ * @private
+ */
+function serverKey(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.origin + parsed.pathname.replace(/\/+$/, '');
+    } catch {
+        return String(url);
+    }
+}
 
 /**
  * Implementation of AWS Auth Backend :: IAM Authentication Method
@@ -51,6 +68,8 @@ class VaultIAMAuth extends VaultBaseAuth {
      * @property {String} [namespace] - Optional. Vault namespace. Applied as the X-Vault-Namespace
      *   header to every request by {@link VaultApiClient}; see {@link VaultClient#constructor}.
      * @property {String} [iam_server_id_header_value] - Optional. Header's value X-Vault-AWS-IAM-Server-ID.
+     *   Without it the signed request names no Vault server, and the first login logs a warning,
+     *   once per Vault server, namespace and mount in a process.
      * @property {String} [region] - Optional. AWS region used to sign the STS GetCallerIdentity
      *   request. When set, the request is signed against the regional STS endpoint
      *   (`sts.<region>.amazonaws.com`) and the SigV4 credential scope is bound to that region.
@@ -80,10 +99,45 @@ class VaultIAMAuth extends VaultBaseAuth {
         this.__credentialChain = credentials ? () => Promise.resolve(credentials) : fromNodeProviderChain();
     }
 
+    /**
+     * Without `X-Vault-AWS-IAM-Server-ID` the signed STS request names no Vault server, so a
+     * server that receives it (or anyone who captures it) can replay it to another Vault server
+     * that trusts the same AWS principal until the signature expires. Warn once per Vault server,
+     * namespace and mount for each logger (once per process on the default logger) when the
+     * header will not be sent or holds only whitespace. Called on login, not in the constructor,
+     * so a client whose construction fails later (in VaultClient) logs nothing. Never throws: a
+     * failure here must not fail the login.
+     * @returns {void}
+     * @private
+     */
+    __warnOnMissingServerId() {
+        try {
+            const value = this.__iam_server_id_header_value;
+            // A value of only whitespace is sent, but names no server either.
+            if (typeof value === 'string' ? value.trim() !== '' : value) {
+                return;
+            }
+            const api = this.__apiClient || {};
+            const key = [serverKey(api.__config && api.__config.url), String(api.__namespace), this._mount]
+                .join('\u0000');
+            warnOnce(
+                this._log,
+                key,
+                'IAM login on mount "%s" is not configured with "iam_server_id_header_value", so the signed '
+                + 'STS request names no Vault server and could be replayed to another one that trusts the same '
+                + 'AWS principal. Set it to the same value as iam_server_id_header_value on auth/%s/config/client',
+                this._mount, this._mount
+            );
+        } catch {
+            // an odd api object changes nothing here
+        }
+    }
+
     /**
      * @inheritDoc
      */
     _authenticate() {
+        this.__warnOnMissingServerId();
         this._log.info(
             'making authentication request: role=%s',
             this.__role

package/src/auth/VaultKubernetesAuth.js

@@ -33,20 +33,27 @@ class VaultKubernetesAuth extends VaultBaseAuth {
             this.__role, this.__tokenPath
         );
 
-        const k8sJwtToken = fs.readFileSync(this.__tokenPath).toString();
-        this._log.debug(
-            'read K8s service-account JWT from "%s" (%d bytes)',
-            this.__tokenPath, k8sJwtToken.length
-        );
-
-        return this.__apiClient.makeRequest('POST', `/auth/${this._mount}/login`, {
-            role: this.__role,
-            jwt: k8sJwtToken,
-        }).then((res) => {
-            this._log.debug('received Vault client token from Kubernetes login');
-
-            return this._getTokenEntity(res.auth.client_token);
-        });
+        // Inside the chain, as in VaultJwtAuth and VaultIAMAuth: a missing or unreadable token
+        // file rejects the login instead of throwing. getAuthToken() turns any backend throw
+        // into a rejection too; this keeps the backend's own _authenticate() contract async.
+        return Promise.resolve()
+            .then(() => {
+                const k8sJwtToken = fs.readFileSync(this.__tokenPath).toString();
+                this._log.debug(
+                    'read K8s service-account JWT from "%s" (%d bytes)',
+                    this.__tokenPath, k8sJwtToken.length
+                );
+
+                return this.__apiClient.makeRequest('POST', `/auth/${this._mount}/login`, {
+                    role: this.__role,
+                    jwt: k8sJwtToken,
+                });
+            })
+            .then((res) => {
+                this._log.debug('received Vault client token from Kubernetes login');
+
+                return this._getTokenEntity(res.auth.client_token);
+            });
     }
 }
 

package/src/errors.d.ts

@@ -12,9 +12,16 @@ export declare class AuthTokenExpiredError extends VaultError {}
 export declare class UnsupportedOperationError extends VaultError {}
 
 export declare class VaultHttpError extends VaultError {
-    constructor(statusCode: number, text: string, body?: unknown);
+    constructor(statusCode: number, text: string, body?: unknown, headers?: { retryAfter?: string | null });
     statusCode: number;
     error: unknown;
+    /** Raw `Retry-After` response header; absent when the response did not send one or it was empty. */
+    retryAfter?: string;
+    /**
+     * `Retry-After` in milliseconds (delay-seconds or HTTP-date), capped at 2147483647;
+     * absent when the header was not sent or cannot be parsed.
+     */
+    retryAfterMs?: number;
 }
 
 export declare class RequestTimeoutError extends VaultError {

package/src/errors.js

@@ -19,6 +19,29 @@ class InvalidAWSCredentialsError extends InvalidArgumentsError {}
 class AuthTokenExpiredError extends VaultError {}
 class UnsupportedOperationError extends VaultError {}
 
+// The longest delay setTimeout() honours; a longer one fires after 1 ms (same limit as api.timeout).
+const MAX_DELAY_MS = 2147483647;
+
+/**
+ * Parses a `Retry-After` header value (RFC 9110 §10.2.3): delay-seconds or an HTTP-date.
+ *
+ * @param {string} value - the raw header value, trimmed and not empty
+ * @param {number} now - current time in milliseconds
+ * @returns {number|undefined} milliseconds to wait, at most MAX_DELAY_MS; `undefined` for a
+ *   value in neither format (e.g. `-5`, or `30, 120` from two headers)
+ */
+function parseRetryAfter(value, now) {
+    if (/^\d+$/.test(value)) {
+        return Math.min(Number(value) * 1000, MAX_DELAY_MS);
+    }
+    // An HTTP-date always names the day or the month; Date.parse() alone also accepts e.g. "-5".
+    const date = /[a-z]/i.test(value) ? Date.parse(value) : NaN;
+    if (Number.isNaN(date)) {
+        return undefined;
+    }
+    return Math.min(Math.max(0, date - now), MAX_DELAY_MS);
+}
+
 /**
  * A non-2xx HTTP response from the Vault server.
  *
@@ -33,11 +56,26 @@ class VaultHttpError extends VaultError {
      * @param {string} text - raw response body text, used in the message.
      * @param {*} [body] - parsed JSON body when the response was valid JSON, the raw text
      *   otherwise, or `undefined` for an empty body. Exposed as `error.error`.
+     * @param {Object} [headers] - response headers the error exposes:
+     * @param {string|null} [headers.retryAfter] - the raw `Retry-After` header, `null` or
+     *   `undefined` when it was not sent. Vault's rate-limit quotas answer 429 with it, in
+     *   seconds; proxies in front of Vault send it with 429 and 503. Exposed as
+     *   `error.retryAfter` (raw) and `error.retryAfterMs` (parsed); both are absent when the
+     *   header was not sent or is empty, and `retryAfterMs` also when it cannot be parsed.
      */
-    constructor(statusCode, text, body) {
+    constructor(statusCode, text, body, { retryAfter } = {}) {
         super(`${statusCode} - ${text}`);
         this.statusCode = statusCode;
         this.error = body;
+
+        const value = typeof retryAfter === 'string' ? retryAfter.trim() : '';
+        if (value !== '') {
+            this.retryAfter = value;
+            const ms = parseRetryAfter(value, Date.now());
+            if (ms !== undefined) {
+                this.retryAfterMs = ms;
+            }
+        }
     }
 }
 

package/src/warnOnce.js

@@ -0,0 +1,44 @@
+'use strict';
+
+/**
+ * Warnings already logged, kept per `logger.warn` function: the default console logger of every
+ * client shares `console.warn`, so the process logs a warning once however many clients it
+ * creates, while a client with a logger of its own still gets it, and the no-op logger of
+ * `logger: false` uses up nobody else's. Each set holds one short string per distinct warning.
+ * @type {WeakMap<Function, Set<string>>}
+ */
+const logged = new WeakMap();
+
+/**
+ * Log `message` with `args` through `logger.warn`, unless that same `logger.warn` has already
+ * logged `message` for `key`. It is recorded only once it has been logged, so a throwing logger
+ * uses nothing up, and this never throws.
+ * @param {Object} logger
+ * @param {string} key - what the warning is about, such as a host or a mount
+ * @param {string} message - the format string
+ * @param {...*} args
+ * @returns {boolean} true when the warning is logged now or was logged before; false when the
+ *      logger threw, so the caller can try again later
+ * @private
+ */
+function warnOnce(logger, key, message, ...args) {
+    try {
+        const warn = logger.warn;
+        const id = `${message}\u0000${key}`;
+        let seen = logged.get(warn);
+        if (seen && seen.has(id)) {
+            return true;
+        }
+        logger.warn(message, ...args);
+        if (!seen) {
+            seen = new Set();
+            logged.set(warn, seen);
+        }
+        seen.add(id);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+module.exports = warnOnce;