node-vault-client 3.2.0 → 3.3.0

package/README.md

@@ -459,6 +459,38 @@ So revoking a client's token no longer locks it out: it logs straight back in wi
 credential. To cut a client off, also revoke or rotate what it logs in with (the AppRole
 `secret_id` or role, the Kubernetes or JWT role binding, the IAM role).
 
+#### Revoking the token on close
+
+By default [`close()`](#VaultClient+close) only cancels the renewal timer: the token stays
+valid on the Vault server until its TTL runs out. Set `revokeOnClose: true` on the `auth` block
+(beside `type`, like the renewal keys) and `close()` also revokes the held token with
+`auth/token/revoke-self`:
+
+```javascript
+auth: {
+    type: 'appRole',
+    revokeOnClose: true,
+    config: { /* ... */ },
+}
+```
+
+The revocation covers the token held when `close()` runs and the one a login still in flight is
+about to produce — that login still resolves after a close, and its token would otherwise
+outlive the client by its whole TTL. `close()` returns the revocation as a promise, so a caller
+that wants certainty can await it; ignoring the return value is fine too, since the request
+itself keeps the process open until it lands. The promise never rejects: a failed revocation is
+logged (`revokeSelf on close failed`) and the token is left live on the Vault server.
+
+Two cautions:
+
+* Under `token` auth the token revoked is the one from your configuration, not one the client
+  issued for itself. The client warns about this combination at construction; only enable it
+  when that token is not shared with anything else.
+* A revoked token cannot be renewed back to life. Calling `close()` and then using the client
+  again logs in once more — with backends that cannot mint a fresh credential (`token`), the
+  next call fails with Vault's 403 (`VaultHttpError`) from `lookup-self`. A request still in
+  flight when the revocation lands surfaces that 403 instead of logging in again.
+
 #### Tuning renewal instead of disabling it
 
 Two further keys, also on `auth`, shape *how* renewal happens. Both are optional, and leaving them
@@ -874,6 +906,11 @@ console.log(secret);
 vaultClient.close(); // process can now exit
 ```
 
+With `auth.revokeOnClose: true` the held token is also revoked on the Vault server
+(`auth/token/revoke-self`), and `close()` returns the revocation as a never-rejecting promise;
+see [Revoking the token on close](#revoking-the-token-on-close). Ignored, the request still
+completes: it keeps the process open until it lands.
+
 **Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
 
 
@@ -1181,8 +1218,8 @@ try {
 
 | Class | Extends | When thrown |
 |---|---|---|
-| `VaultError` | `Error` | Base class for every error below. Raised directly when mount detection fails (e.g. permission denied) and no `api.engines` override was provided; the failure is on `cause`, so Vault's HTTP status is `err.cause.statusCode`. Vault answers 403 both for a mount the token may not use and for one that does not exist. |
-| `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. |
+| `VaultError` | `Error` | Base class for every error below. Raised directly when mount detection fails (e.g. permission denied) and no `api.engines` override was provided; the failure is on `cause`, so Vault's HTTP status is `err.cause.statusCode`, and a rate-limited detection's `Retry-After` is `err.cause.retryAfter` / `err.cause.retryAfterMs`. Vault answers 403 both for a mount the token may not use and for one that does not exist. |
+| `VaultHttpError` | `VaultError` | Vault answered with a non-2xx status. Carries the status as `statusCode` and the parsed body as `error`. When the response sent a `Retry-After` header (Vault's own rate-limit quotas answer 429 with it, in seconds; a proxy in front of Vault may send it with 429 or 503), it is on `retryAfter` as sent and on `retryAfterMs` in milliseconds: delay-seconds and HTTP-dates are both parsed, the result is capped at 2147483647 (the longest `setTimeout()` delay), and `retryAfterMs` is absent when the value is in neither format. Prefer `retryAfterMs` to parsing `retryAfter` yourself, and clamp it to what your caller can afford to wait. The client does not wait and retry on `Retry-After` itself (token renewal retries do not honour it yet). `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 or `api.timeout`, an invalid node-config substitution map, or a KV method path that fails [path validation](#path-validation). |
 | `InvalidAWSCredentialsError` | `InvalidArgumentsError` | `auth.config.credentials` was supplied but is not a usable `accessKeyId` / `secretAccessKey` pair. |
 | `AuthTokenExpiredError` | `VaultError` | The Vault token expired and the backend cannot obtain a new one. `token` auth can never re-authenticate and reaches this error at max TTL even with renewal enabled; other backends can also reach it when re-authentication is disabled or their credential can no longer be replayed. |

package/index.d.ts

@@ -22,7 +22,7 @@ declare class VaultClient {
 
     fillNodeConfig(): Promise<any>;
     getHeaders(token: VaultClient.AuthToken): Record<string, string>;
-    close(): void;
+    close(): Promise<void> | null | undefined;
 }
 
 declare namespace VaultClient {
@@ -103,6 +103,7 @@ declare namespace VaultClient {
         renewal?: boolean;
         renewalFraction?: number;
         renewalIncrement?: number;
+        revokeOnClose?: boolean;
     }
 
     type AuthOptions = AuthOptionsCommon &

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-vault-client",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "A Vault Client implemented in pure javascript for HashiCorp Vault. It supports variety of Auth Backends and performs lease renewal for issued auth token.",
   "repository": {
     "url": "git+https://github.com/namecheap/node-vault-client.git"

package/src/VaultApiClient.js

@@ -390,7 +390,10 @@ class VaultApiClient {
                 }
 
                 if (!response.ok) {
-                    throw new errors.VaultHttpError(response.status, text, body);
+                    // headers?.: fetch test doubles in callers' suites often have no headers
+                    throw new errors.VaultHttpError(response.status, text, body, {
+                        retryAfter: response.headers?.get('retry-after'),
+                    });
                 }
 
                 // Do not log the response body: Vault responses carry secret

package/src/VaultClient.js

@@ -254,6 +254,10 @@ class VaultClient {
      * @param {number} [options.auth.renewalIncrement] - Seconds of extra TTL to request on each
      *      renewal, sent as `increment` to `auth/token/renew-self`. Vault caps it at the token's
      *      max TTL. Omitted by default, which lets Vault apply the token's own period.
+     * @param {boolean} [options.auth.revokeOnClose=false] - Set `true` to revoke the held token
+     *      (`auth/token/revoke-self`) when {@link VaultClient#close} runs. The token the
+     *      `token` backend was configured with is revoked too, so only enable it when that
+     *      token is not shared with anything else.
      * @param {Object|false} options.logger - Logger that supports "error", "info", "warn", "trace", "debug" methods. Uses `console` by default. Pass `false` to disable logging.
      */
     constructor(options) {
@@ -288,6 +292,13 @@ class VaultClient {
         // `namespace` to `api.namespace`.
         this.__auth.configureRenewal(options.auth);
 
+        if (options.auth && options.auth.revokeOnClose === true && options.auth.type === 'token') {
+            this.__log.warn(
+                'auth.revokeOnClose revokes the token from the configuration itself on close(); ' +
+                'enable it only when that token is not shared with anything else'
+            );
+        }
+
         // KV v2 support
         const kvOpts = (options.api && options.api.kv) || {};
         const autoDetect = kvOpts.autoDetect === true;
@@ -428,7 +439,15 @@ class VaultClient {
      * login already in flight when `close()` runs still resolves, but arms no timer, and
      * neither does a call that joins that login after `close()`.
      *
-     * @returns {void}
+     * With `auth.revokeOnClose: true` the held token is also revoked on the Vault server
+     * (`auth/token/revoke-self`): the one held now, or the one a login still in flight is
+     * about to produce. The revocation request keeps the event loop open until it lands, so
+     * a short-lived script that ignores the return value still completes it.
+     *
+     * @returns {Promise<void>|null|undefined} `null` (or `undefined` for an auth provider
+     *      without revocation support) when there is nothing to revoke, otherwise a
+     *      promise for the revocation. It never rejects: a failed revocation is logged and
+     *      the token is left live on the Vault server.
      */
     close() {
         if (this.__auth && typeof this.__auth.__markClosed === 'function') {
@@ -438,6 +457,12 @@ class VaultClient {
         if (this.__auth && typeof this.__auth.cancelTokenRefresh === 'function') {
             this.__auth.cancelTokenRefresh();
         }
+        if (this.__auth && typeof this.__auth.revokeSelfOnClose === 'function') {
+            // null unless auth.revokeOnClose started a revocation. Fire-and-forget when
+            // ignored (clear() does that): the request holds the event loop open until it
+            // lands. Returned so a caller that wants certainty can await it.
+            return this.__auth.revokeSelfOnClose();
+        }
     }
 
     /**

package/src/auth/VaultBaseAuth.js

@@ -162,6 +162,19 @@ class VaultBaseAuth {
          * @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;
     }
 
     /**
@@ -173,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);
     }
 
     /**
@@ -204,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}
@@ -346,6 +385,75 @@ class VaultBaseAuth {
         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
@@ -363,6 +471,12 @@ class VaultBaseAuth {
             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);
         }

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;
+            }
+        }
     }
 }