node-vault-client 1.0.2 → 2.0.0

package/README.md

@@ -1,7 +1,10 @@
 # Node.js Vault Client
 
-![npm](https://img.shields.io/npm/v/node-vault-client)
-![npm](https://img.shields.io/npm/dm/node-vault-client)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/namecheap/node-vault-client/pipeline.yaml?branch=master&style=flat-square)](https://github.com/namecheap/node-vault-client/actions/workflows/pipeline.yaml)
+[![Download Status](https://img.shields.io/npm/dm/node-vault-client.svg?style=flat-square)](https://www.npmjs.com/package/node-vault-client)
+[![NPM Version](https://img.shields.io/npm/v/node-vault-client?style=flat-square)](https://www.npmjs.com/package/node-vault-client)
+[![License](https://img.shields.io/npm/l/node-vault-client?style=flat-square)](https://github.com/namecheap/node-vault-client/blob/master/LICENSE.txt)
+[![Dependency Status](https://img.shields.io/librariesio/release/npm/node-vault-client.svg?style=flat-square)](https://libraries.io/npm/node-vault-client/)
 
 A Vault Client implemented in pure javascript for [HashiCorp Vault](https://github.com/hashicorp/vault).
 It supports variety of Auth Backends and performs lease renewal for issued auth token.
@@ -11,6 +14,10 @@ It supports variety of Auth Backends and performs lease renewal for issued auth
 npm install --save node-vault-client
 ```
 
+### Requirements
+
+Node.js >= 18 — the client uses the native `fetch` API.
+
 ## Example
 
 ```javascript
@@ -19,21 +26,102 @@ const VaultClient = require('node-vault-client');
 const vaultClient = VaultClient.boot('main', {
     api: { url: 'https://vault.example.com:8200/' },
     auth: { 
-        type: 'appRole', // or 'token', 'iam'
+        type: 'appRole', // one of: 'appRole' | 'token' | 'iam' | 'kubernetes'
         config: { role_id: '637c065f-c644-5e12-d3d1-e9fa4363af61' } 
     },
 });
 
-vaultClient.read('secret/tst').then(v => {
-    console.log(v);
+vaultClient.read('secret/tst').then(lease => {
+    console.log(lease.getData()); // read() resolves to a Lease; use getData()/getValue(key)
 }).catch(e => console.error(e));
 ```
 
 ## Supported Auth Backends
 
-* [AWS IAM](https://www.vaultproject.io/docs/auth/aws.html#iam-auth-method)
-* [AppRole](https://www.vaultproject.io/docs/auth/approle.html)
-* [Token](https://www.vaultproject.io/docs/auth/token.html)
+* [AWS IAM](https://developer.hashicorp.com/vault/docs/auth/aws)
+* [AppRole](https://developer.hashicorp.com/vault/docs/auth/approle)
+* [Token](https://developer.hashicorp.com/vault/docs/auth/token)
+* [Kubernetes](https://developer.hashicorp.com/vault/docs/auth/kubernetes)
+
+### AWS IAM auth
+
+```javascript
+const vaultClient = VaultClient.boot('main', {
+    api: { url: 'https://vault.example.com:8200/' },
+    auth: {
+        type: 'iam',
+        mount: 'aws',                                  // Optional. Vault AWS auth mount point ("aws" by default)
+        config: {
+            role: 'my_iam_role',
+            iam_server_id_header_value: 'https://vault.example.com:8200/', // Optional. X-Vault-AWS-IAM-Server-ID header
+            namespace: 'some_namespace',               // Optional. X-Vault-Namespace header
+            region: 'eu-central-1',                     // Optional. AWS STS region (see below)
+            credentials: {                             // Optional. Resolved from the AWS provider chain when omitted
+                accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+                secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+            },
+        },
+    },
+});
+```
+
+#### `region`
+
+By default the signed `GetCallerIdentity` request targets the global STS endpoint
+`sts.amazonaws.com` and the SigV4 credential scope is bound to `us-east-1`. Set
+`config.region` to sign against a regional STS endpoint instead — the request is then sent to
+`sts.<region>.amazonaws.com` and the signature scope is bound to that region. This is required
+when Vault's `sts_region` / `sts_endpoint` is configured for a non-`us-east-1` region (e.g.
+`eu-central-1`); otherwise STS rejects the replayed request with
+`SignatureDoesNotMatch — Credential should be scoped to a valid region`. Omitting `region`
+preserves the previous (global-endpoint) behavior.
+
+### AppRole auth
+
+```javascript
+const vaultClient = VaultClient.boot('main', {
+    api: { url: 'https://vault.example.com:8200/' },
+    auth: {
+        type: 'appRole',
+        mount: 'approle',                              // Optional. Vault AppRole auth mount point ("approle" by default)
+        config: {
+            role_id: '637c065f-c644-5e12-d3d1-e9fa4363af61', // Required. RoleID of the AppRole
+            secret_id: '...',                          // Optional. Required when bind_secret_id is enabled
+        },
+    },
+});
+```
+
+### Token auth
+
+```javascript
+const vaultClient = VaultClient.boot('main', {
+    api: { url: 'https://vault.example.com:8200/' },
+    auth: {
+        type: 'token',
+        mount: 'token',                                // Optional. Vault token auth mount point ("token" by default)
+        config: {
+            token: 's.xxxxxxxxxxxxxxxxxxxxxxxx',       // Required. Vault token
+        },
+    },
+});
+```
+
+### Kubernetes auth
+
+```javascript
+const vaultClient = VaultClient.boot('main', {
+    api: { url: 'https://vault.example.com:8200/' },
+    auth: {
+        type: 'kubernetes',
+        mount: 'kubernetes',                           // Optional. Vault Kubernetes auth mount point ("kubernetes" by default)
+        config: {
+            role: 'my_k8s_role',                       // Required. Role configured in the Vault Kubernetes auth backend
+            tokenPath: '/var/run/secrets/kubernetes.io/serviceaccount/token', // Optional. Defaults to the in-pod service-account token path
+        },
+    },
+});
+```
 
 ## API
 
@@ -47,11 +135,13 @@ vaultClient.read('secret/tst').then(v => {
         * [.fillNodeConfig()](#VaultClient+fillNodeConfig)
         * [.read(path)](#VaultClient+read) ⇒ <code>Promise.&lt;Lease&gt;</code>
         * [.list(path)](#VaultClient+list) ⇒ <code>Promise.&lt;Lease&gt;</code>
-        * [.write(path, data)](#VaultClient+write) ⇒ <code>Promise.&lt;(T\|never)&gt;</code>
+        * [.write(path, data)](#VaultClient+write) ⇒ <code>Promise.&lt;Object&gt;</code>
+        * [.close()](#VaultClient+close)
     * _static_
-        * [.boot(name, [options])](#VaultClient.boot) ⇒
-        * [.get(name)](#VaultClient.get) ⇒
+        * [.boot(name, [options])](#VaultClient.boot) ⇒ <code>VaultClient</code>
+        * [.get(name)](#VaultClient.get) ⇒ <code>VaultClient</code>
         * [.clear([name])](#VaultClient.clear)
+* [Lease](#Lease)
 
 <a name="new_VaultClient_new"></a>
 
@@ -65,14 +155,52 @@ Client constructor function.
 | options.api | <code>Object</code> |  |  |
 | options.api.url | <code>String</code> |  | the url of the vault server |
 | [options.api.apiVersion] | <code>String</code> | `v1` |  |
+| [options.api.requestOptions] | <code>Object</code> |  | extra options merged into every HTTP request (see [Custom transport](#custom-transport-proxy--self-signed-tls)) |
 | options.auth | <code>Object</code> |  |  |
 | options.auth.type | <code>String</code> |  |  |
+| [options.auth.mount] | <code>String</code> |  | Vault auth backend mount point; default varies per method (e.g. "aws" for iam, "approle", "token", "kubernetes") |
 | options.auth.config | <code>Object</code> |  | auth configuration variables |
+| [options.auth.config.namespace] | <code>String</code> |  | Optional. Vault namespace, sent as the `X-Vault-Namespace` header on all secret read/list/write requests. Applies to every auth type, not just IAM. |
 | options.logger | <code>Object</code> | `false` |  | Logger that supports "error", "info", "warn", "trace", "debug" methods. Uses `console` by default. Pass `false` to disable logging. |
 
-#### vaultClient.fillNodeConfig()
+##### Custom transport (proxy / self-signed TLS)
+
+`options.api.requestOptions` is shallow-merged into every underlying `fetch()` call, so you
+can route traffic through a proxy/SOCKS agent or trust a self-signed / internal-CA Vault.
+Pass an [undici](https://undici.nodejs.org/) `dispatcher` (request semantics like `method`
+and `body` always win; `headers` are merged with per-request headers taking precedence):
+
+```javascript
+const { Agent, ProxyAgent } = require('undici');
+
+// Trust an internal/self-signed CA (preferred over disabling verification)
+const vaultClient = VaultClient.boot('main', {
+    api: {
+        url: 'https://vault.internal:8200/',
+        requestOptions: {
+            dispatcher: new Agent({ connect: { ca: require('fs').readFileSync('/etc/ssl/internal-ca.pem') } }),
+        },
+    },
+    auth: { type: 'token', config: { token: '...' } },
+});
+
+// Route through an HTTP proxy / SOCKS agent
+const proxied = VaultClient.boot('proxied', {
+    api: { url: 'https://vault.example.com:8200/', requestOptions: { dispatcher: new ProxyAgent('http://proxy:8080') } },
+    auth: { type: 'token', config: { token: '...' } },
+});
+```
+
+For the self-signed-CA case you can also use the process-wide `NODE_EXTRA_CA_CERTS=/path/ca.pem`
+env var with no code change. Only disable verification
+(`new Agent({ connect: { rejectUnauthorized: false } })`) in throwaway/dev setups — it removes
+MITM protection.
+
+#### vaultClient.fillNodeConfig() ⇒ <code>Promise</code>
 Populates Vault's values to NPM "config" module
 
+Resolves once the npm `config` module has been populated from Vault.
+
 **Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
 <a name="VaultClient+read"></a>
 
@@ -98,9 +226,12 @@ Retrieves secrets list
 
 <a name="VaultClient+write"></a>
 
-#### vaultClient.write(path, data) ⇒ <code>Promise.&lt;(T\|never)&gt;</code>
+#### vaultClient.write(path, data) ⇒ <code>Promise.&lt;Object&gt;</code>
 Writes data to Vault
 
+Resolves to the raw parsed Vault response body, which may be empty/undefined for
+`204 No Content` responses.
+
 **Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
 
 | Param | Type | Description |
@@ -108,16 +239,48 @@ Writes data to Vault
 | path |  | path used to write data |
 | data | <code>object</code> | data to write |
 
+<a name="VaultClient+close"></a>
+
+#### vaultClient.close()
+Release resources held by this client.
+
+This client performs lease renewal for renewable auth tokens by arming a background timer.
+That timer keeps the Node.js event loop alive, so a short-lived script (e.g. a one-off
+`read`) never exits on its own. Call `close()` once you are done with the client to cancel
+the timer and let the process exit. It is null-safe and safe to call multiple times. The
+client may still be used afterwards — the next operation that fetches a renewable token
+will arm a new refresh timer.
+
+```javascript
+const vaultClient = VaultClient.boot('main', { /* ... */ });
+const secret = await vaultClient.read('secret/tst');
+console.log(secret);
+vaultClient.close(); // process can now exit
+```
+
+**Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
+
+<a name="Lease"></a>
+
+### Lease
+
+The object returned by `read()` and `list()` (they resolve to `Promise<Lease>`). Use its
+accessors to extract the secret data:
+
+* `getValue(key)` ⇒ <code>String</code> — value for a single key. Throws `Requested key does not exist` when the key is absent.
+* `getData()` ⇒ <code>Object</code> — a deep-cloned copy of the whole secret data object.
+* `isRenewable()` ⇒ <code>boolean</code> — whether the underlying lease is renewable.
+
 <a name="VaultClient.boot"></a>
 
-#### VaultClient.boot(name, [options]) ⇒
+#### VaultClient.boot(name, [options]) ⇒ <code>VaultClient</code>
 Boot an instance of Vault
 
 The instance will be stored in a local hash. Calling Vault.boot multiple
 times with the same name will return the same instance.
 
 **Kind**: static method of [<code>VaultClient</code>](#VaultClient)  
-**Returns**: Vault  
+**Returns**: <code>VaultClient</code>  
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -126,14 +289,14 @@ times with the same name will return the same instance.
 
 <a name="VaultClient.get"></a>
 
-#### VaultClient.get(name) ⇒
+#### VaultClient.get(name) ⇒ <code>VaultClient</code>
 Get an instance of Vault
 
 The instance will be stored in a local hash. Calling Vault.pop multiple
 times with the same name will return the same instance.
 
 **Kind**: static method of [<code>VaultClient</code>](#VaultClient)  
-**Returns**: Vault  
+**Returns**: <code>VaultClient</code>  
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -151,3 +314,24 @@ If no name passed all named instances will be cleared.
 | Param | Type | Description |
 | --- | --- | --- |
 | [name] | <code>String</code> | Vault instance name, all instances will be cleared if no name were passed |
+
+## Contributing
+
+Contributions are welcome! Please read the [contributing guide](CONTRIBUTING.md) to get started,
+and note that this project requires a [DCO sign-off](CONTRIBUTING.md#dco-sign-off) on every commit.
+
+## Getting help
+
+Not sure where to start? See [SUPPORT.md](SUPPORT.md).
+
+## Code of Conduct
+
+This project adheres to the [Contributor Covenant Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+To report a security vulnerability, please follow our [Security Policy](SECURITY.md).
+
+## License
+
+Licensed under the [Apache License 2.0](LICENSE.txt).

package/package.json

@@ -1,21 +1,35 @@
 {
   "name": "node-vault-client",
-  "version": "1.0.2",
+  "version": "2.0.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"
   },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=18.0.0"
   },
   "main": "src/VaultClient.js",
   "files": [
     "src"
   ],
   "scripts": {
-    "test": "mocha test/**/*.test.js",
+    "test": "mocha --exit \"test/**/*.test.mjs\"",
+    "test:unit": "mocha \"test/*.test.mjs\"",
+    "coverage": "c8 npm run test:unit",
+    "lint": "eslint src/",
     "version": "git add -A ."
   },
+  "c8": {
+    "include": [
+      "src/**/*.js"
+    ],
+    "reporter": [
+      "text",
+      "html",
+      "lcov"
+    ],
+    "all": true
+  },
   "author": "Namecheap <opensource@namecheap.com>",
   "license": "Apache-2.0",
   "dependencies": {
@@ -26,19 +40,25 @@
     "lodash": "^4.17.15",
     "long-timeout": "^0.1.1",
     "pretty-ms": "^2.1.0",
-    "request": "^2.88.0",
-    "request-promise": "^4.2.4",
     "url-join": "^2.0.5"
   },
   "peerDependencies": {
     "config": ">=1 <4"
   },
+  "overrides": {
+    "serialize-javascript": "^7.0.5",
+    "glob": "^13.0.0",
+    "diff": "^8.0.3"
+  },
   "devDependencies": {
-    "chai": "^3.5.0",
-    "co-mocha": "^1.2.2",
+    "@eslint/js": "^9.0.0",
+    "c8": "^11.0.0",
+    "chai": "^6.0.0",
     "deep-freeze": "^0.0.1",
-    "mocha": "^3.5.3",
-    "sinon": "^2.4.1",
-    "sinon-chai": "^2.14.0"
+    "eslint": "^9.0.0",
+    "globals": "^16.0.0",
+    "mocha": "^11.7.6",
+    "sinon": "^22.0.0",
+    "sinon-chai": "^4.0.0"
   }
 }

package/src/VaultApiClient.js

@@ -1,6 +1,5 @@
 'use strict';
 
-const rp = require('request-promise');
 const urljoin = require('url-join');
 const _ = require('lodash');
 
@@ -10,13 +9,25 @@ class VaultApiClient {
      * @param {Object} config
      * @param {String} config.url - the url of the vault server
      * @param {String} [config.apiVersion='v1']
+     * @param {Object} [config.requestOptions] - extra options shallow-merged into every
+     *      `fetch()` call. Use it to inject an undici `dispatcher` for a proxy/SOCKS agent
+     *      or for custom TLS trust (self-signed / internal CA). Request-specific fields
+     *      (`method`, `body`) always take precedence; `headers` are merged with the
+     *      per-request headers winning. Stored by reference (not deep-cloned) so live
+     *      objects such as a Dispatcher keep their prototype and remain usable.
      * @param {Object} logger
      */
     constructor(config, logger) {
-        this.__config = _.defaultsDeep(_.cloneDeep(config), {
+        const requestOptions = config && config.requestOptions;
+
+        this.__config = _.defaultsDeep(_.cloneDeep(_.omit(config, ['requestOptions'])), {
             apiVersion: 'v1',
         });
 
+        if (requestOptions !== undefined) {
+            this.__config.requestOptions = requestOptions;
+        }
+
         this._logger = logger;
     }
 
@@ -24,31 +35,59 @@ class VaultApiClient {
         data = data === undefined ? null : data;
         headers = headers === undefined ? {} : headers;
 
-        const requestOptions = {
-            method: method,
-            body: data === null ? undefined : data,
-            uri: urljoin(this.__config.url, this.__config.apiVersion, path),
-            followRedirects: true,
-            followAllRedirects: true,
-            headers,
-            json: true,
-        };
+        const uri = urljoin(this.__config.url, this.__config.apiVersion, path);
+
+        const requestOptions = this.__config.requestOptions || {};
+
+        const options = Object.assign(
+            { redirect: 'follow' },
+            requestOptions,
+            {
+                method: method,
+                headers: Object.assign(
+                    { Accept: 'application/json' },
+                    requestOptions.headers,
+                    headers
+                ),
+            }
+        );
+        if (data !== null) {
+            options.body = JSON.stringify(data);
+            options.headers['Content-Type'] = 'application/json';
+        }
 
         this._logger.debug(
             'making request: %s %s',
-            requestOptions.method,
-            requestOptions.uri
+            method,
+            uri
         );
 
-        return rp(requestOptions)
-            .then((response) => {
+        return fetch(uri, options).then((response) => {
+            return response.text().then((text) => {
+                let body;
+                if (text) {
+                    try {
+                        body = JSON.parse(text);
+                    } catch {
+                        body = text;
+                    }
+                }
+
+                if (!response.ok) {
+                    const error = new Error(`${response.status} - ${text}`);
+                    error.statusCode = response.status;
+                    error.error = body;
+                    throw error;
+                }
+
                 this._logger.debug('%s %s response body:\n%s',
-                    requestOptions.method,
-                    requestOptions.uri,
-                    JSON.stringify(response, null, ' ')
+                    method,
+                    uri,
+                    JSON.stringify(body, null, ' ')
                 );
-                return response;
+                return body;
             });
+        });
     }
 }
 

package/src/VaultClient.js

@@ -20,6 +20,9 @@ class VaultClient {
      * @param {Object} options.api
      * @param {String} options.api.url - the url of the vault server
      * @param {String} [options.api.apiVersion='v1']
+     * @param {Object} [options.api.requestOptions] - extra options merged into every HTTP
+     *      request (e.g. an undici `dispatcher` for a proxy/SOCKS agent or custom TLS/CA trust).
+     *      See {@link VaultApiClient#constructor}.
      * @param {Object} options.auth
      * @param {String} options.auth.type
      * @param {Object} options.auth.config - auth configuration variables
@@ -52,8 +55,8 @@ class VaultClient {
      * times with the same name will return the same instance.
      *
      * @param {String} name - Vault instance name
-     * @param {Object} [options] - options for {@link Vault#constructor}.
-     * @return Vault
+     * @param {Object} [options] - options for {@link VaultClient#constructor}.
+     * @return {VaultClient}
      */
     static boot(name, options) {
         if (options === undefined) {
@@ -74,7 +77,7 @@ class VaultClient {
      * times with the same name will return the same instance.
      *
      * @param {String} name - Vault instance name
-     * @return Vault
+     * @return {VaultClient}
      */
     static get(name) {
         let instance = vaultInstances[name];
@@ -95,16 +98,38 @@ class VaultClient {
      */
     static clear(name) {
         if (typeof name === 'string') {
-            delete vaultInstances[name];
+            const instance = vaultInstances[name];
+            if (instance !== undefined) {
+                instance.close();
+                delete vaultInstances[name];
+            }
         } else {
             for (let k in vaultInstances) {
-                if (vaultInstances.hasOwnProperty(k)) {
+                if (Object.hasOwn(vaultInstances, k)) {
+                    vaultInstances[k].close();
                     delete vaultInstances[k];
                 }
             }
         }
     }
 
+    /**
+     * Release resources held by this client.
+     *
+     * Cancels the background auth-token refresh timer that keeps the Node.js event loop
+     * alive for renewable tokens. Call this once you are done with the client so a
+     * short-lived script can exit on its own. Safe to call when no timer is armed and
+     * safe to call multiple times. After calling `close()` the client may still be used;
+     * the next operation that fetches a renewable token will arm a new refresh timer.
+     *
+     * @returns {void}
+     */
+    close() {
+        if (this.__auth && typeof this.__auth.cancelTokenRefresh === 'function') {
+            this.__auth.cancelTokenRefresh();
+        }
+    }
+
     /**
      * @protected
      *
@@ -215,9 +240,9 @@ class VaultClient {
     /**
      * Writes data to Vault
      *
-     * @param path - path used to write data
+     * @param {string} path - path used to write data
      * @param {object} data - data to write
-     * @returns {Promise<T | never>}
+     * @returns {Promise<Object>} the parsed Vault response body
      */
     write(path, data) {
         this.__log.debug('write secret %s', path);

package/src/VaultNodeConfig.js

@@ -1,7 +1,6 @@
 'use strict';
 
 const path = require('path');
-const fs = require('fs');
 const Bluebird = require('bluebird');
 const _ = require('lodash');
 const assignDeep = require('assign-deep');
@@ -15,7 +14,7 @@ class VaultNodeConfig {
 
         try {
             require.resolve('config');
-        } catch(e) {
+        } catch {
             throw new errors.VaultError(`NPM package "config" isn't installed`);
         }
 
@@ -73,7 +72,7 @@ class VaultNodeConfig {
         let fileContent;
         try {
             fileContent = require(fullFilename);
-        } catch (e) {
+        } catch {
             throw new errors.VaultError('Config file ' + fullFilename + ' cannot be read');
         }
 
@@ -86,7 +85,7 @@ class VaultNodeConfig {
 
     __traverse(o, func) {
         for (let i in o) {
-            if (!o.hasOwnProperty(i)) {
+            if (!Object.hasOwn(o, i)) {
                 continue;
             }
 

package/src/auth/AuthToken.js

@@ -1,6 +1,5 @@
 'use strict';
 
-const _ = require('lodash');
 
 class AuthToken {
 
@@ -35,25 +34,73 @@ class AuthToken {
     static fromResponse(response) {
         const data = response.data;
 
-        let expiresAt = null;
-        if (data.ttl !== 0) {
-            const creationTime = parseInt(data.last_renewal_time !== undefined ? data.last_renewal_time : data.creation_time, 10);
-            const networkLatency = 60;
-            const ttl = parseInt(data.ttl > networkLatency ? data.ttl - networkLatency : data.ttl);
-            expiresAt = creationTime + ttl;
-        }
-
         return new AuthToken(
             data.id,
             data.accessor,
             data.creation_time,
-            expiresAt,
+            AuthToken.__resolveExpiresAt(data),
             data.explicit_max_ttl,
             data.num_uses,
             data.renewable !== undefined ? data.renewable : false
         );
     }
 
+    /**
+     * 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.
+     *
+     * Prefers Vault's authoritative `expire_time` (RFC3339), which is the documented
+     * absolute expiry. Falls back to `(last_renewal_time || creation_time) + ttl` for
+     * responses that don't carry `expire_time` — note `ttl` is the *remaining* lifetime,
+     * so that sum is only accurate when the lookup happens right after issuance/renewal.
+     *
+     * @private
+     * @param {Object} data - the `data` object of a token lookup response
+     * @returns {int|null} null when the token never expires (ttl === 0)
+     */
+    static __resolveExpiresAt(data) {
+        if (data.ttl === 0) {
+            return null;
+        }
+
+        const networkLatency = 60;
+        const margin = data.ttl > networkLatency ? networkLatency : 0;
+
+        const expireTime = AuthToken.__parseRfc3339Seconds(data.expire_time);
+        if (expireTime !== null) {
+            return expireTime - margin;
+        }
+
+        // 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);
+    }
+
+    /**
+     * 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,
+     * 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) {
+        if (typeof value !== 'string' || value === '') {
+            return null;
+        }
+
+        const ms = Date.parse(value);
+        if (isNaN(ms)) {
+            return null;
+        }
+
+        const seconds = Math.floor(ms / 1000);
+        return seconds > 0 ? seconds : null;
+    }
+
     /**
      * @returns {string}
      */

package/src/auth/VaultAppRoleAuth.js

@@ -6,9 +6,11 @@ class VaultAppRoleAuth extends VaultBaseAuth {
 
     /**
      * @param {VaultApiClient} apiClient - see {@link VaultBaseAuth#constructor}
+     * @param {Object} logger
      * @param {Object} config
      * @param {String} config.role_id - RoleID of the AppRole.
      * @param {String} [config.secret_id] - required when bind_secret_id is enabled SecretID belonging to AppRole.
+     * @param {String} [config.namespace] - Optional. Vault namespace, sent as the X-Vault-Namespace header.
      * @param {String} mount - Vault's  mount point ("approle" by default)
      */
     constructor(apiClient, logger, config, mount) {

package/src/auth/VaultBaseAuth.js

@@ -32,11 +32,15 @@ class VaultBaseAuth {
     }
 
     getAuthToken() {
-        if (this.__authToken === null || (this.__authToken instanceof AuthToken && this.__authToken.isExpired() && this._reauthenticationAllowed())) {
-            if (this.__authToken !== null && this.__authToken.isExpired() && !this._reauthenticationAllowed()) {
-                throw new errors.AuthTokenExpiredError('Auth token has expired & cannot be refreshed since auth method doesn\'t support this.');
-            }
+        const tokenExpired = this.__authToken instanceof AuthToken && this.__authToken.isExpired();
 
+        if (tokenExpired && !this._reauthenticationAllowed()) {
+            return Promise.reject(new errors.AuthTokenExpiredError(
+                'Auth token has expired & cannot be refreshed since auth method doesn\'t support this.'
+            ));
+        }
+
+        if (this.__authToken === null || tokenExpired) {
             this._log.info('getting auth token (mount=%s)', this._mount);
 
             const tokenPromise = this._authenticate().then(authToken => {
@@ -64,6 +68,24 @@ class VaultBaseAuth {
         return Promise.resolve(this.__authToken);
     }
 
+    /**
+     * Cancel any pending token-refresh timer.
+     *
+     * When a renewable token is fetched the client arms a `long-timeout` timer to renew it
+     * before it expires. That timer keeps the Node.js event loop alive, so a short-lived
+     * script never exits on its own. Call this (or {@link VaultClient#close}) once you are
+     * done with the client to release the event loop. Safe to call when no timer is armed
+     * and safe to call multiple times.
+     *
+     * @returns {void}
+     */
+    cancelTokenRefresh() {
+        if (this.__refreshTimeout !== null) {
+            lt.clearTimeout(this.__refreshTimeout);
+            this.__refreshTimeout = null;
+        }
+    }
+
     /**
      * @protected
      * @returns {Promise<AuthToken>}

package/src/auth/VaultIAMAuth.js

@@ -29,6 +29,7 @@ const errors = require('../errors');
  *               role: 'my_iam_role',
  *               iam_server_id_header_value: VAULT_ADDR,   // Optional
  *               namespace: 'some_namespace',              // Optional
+ *               region: 'eu-central-1',                   // Optional. AWS STS region.
  *               credentials: {                            // Optional
  *                 accessKeyId: AWS_ACCESS_KEY,
  *                 secretAccessKey: AWS_SECRET_KEY,
@@ -47,8 +48,14 @@ class VaultIAMAuth extends VaultBaseAuth {
      *
      * @typedef {Object} VaultIAMAuthConfig
      * @property {String} role - Role name of the auth/{mount}/role/{name} backend.
-     * @property [AWSCredentials] [credentials] - Optional. AWS Credentials
+     * @property {AWSCredentials} [credentials] - Optional. AWS Credentials
+     * @property {String} [namespace] - Optional. Vault namespace, sent as the X-Vault-Namespace header.
      * @property {String} [iam_server_id_header_value] - Optional. Header's value X-Vault-AWS-IAM-Server-ID.
+     * @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.
+     *   When omitted, the global endpoint (`sts.amazonaws.com`, scope `us-east-1`) is used,
+     *   preserving the previous default behavior.
      *
      * @param {VaultApiClient} api - see {@link VaultBaseAuth#constructor}
      * @param {Object} logger
@@ -61,6 +68,7 @@ class VaultIAMAuth extends VaultBaseAuth {
         this.__role = config.role;
         this.__iam_server_id_header_value = config.iam_server_id_header_value;
         this.__namespace = config.namespace;
+        this.__region = config.region;
 
 
         const { credentials } = config;
@@ -130,7 +138,11 @@ class VaultIAMAuth extends VaultBaseAuth {
                 JSON.stringify(this.__headersLikeGolangStyle(stsRequest.headers))
             ),
             iam_request_body: this.__base64encode(stsRequest.body),
-            iam_request_url: this.__base64encode(`https://${stsRequest.hostname}${stsRequest.path}`),
+            // `aws4` populates `hostname` for the default (global) endpoint, but
+            // `host` when an explicit host is supplied (regional endpoint). Use
+            // whichever is present so the URL sent to Vault matches the signed
+            // Host header.
+            iam_request_url: this.__base64encode(`https://${stsRequest.host || stsRequest.hostname}${stsRequest.path}`),
             role: this.__role
         }
     }
@@ -142,14 +154,27 @@ class VaultIAMAuth extends VaultBaseAuth {
      * @private
      */
     __getStsRequest(credentials) {
-        return aws4.sign({
+        const request = {
             service: 'sts',
             method: 'POST',
             body: 'Action=GetCallerIdentity&Version=2011-06-15',
             headers: this.__iam_server_id_header_value ? {
                 'X-Vault-AWS-IAM-Server-ID': this.__iam_server_id_header_value,
             } : {}
-        }, credentials);
+        };
+
+        // When a region is configured, sign the request against the regional STS
+        // endpoint. Both the SigV4 credential scope (via `region`) and the signed
+        // Host header / request URL (via `host`) must reference the same region,
+        // otherwise Vault's STS replay fails with `SignatureDoesNotMatch`.
+        // When omitted, `aws4` defaults to the global endpoint (`sts.amazonaws.com`,
+        // scope `us-east-1`), preserving the previous behavior.
+        if (this.__region) {
+            request.region = this.__region;
+            request.host = `sts.${this.__region}.amazonaws.com`;
+        }
+
+        return aws4.sign(request, credentials);
     }
 
     /**
@@ -157,7 +182,7 @@ class VaultIAMAuth extends VaultBaseAuth {
      * @private
      */
     __base64encode(string) {
-        return new Buffer(string).toString('base64')
+        return Buffer.from(string).toString('base64')
     }
 
     /**

package/src/auth/VaultKubernetesAuth.js

@@ -4,6 +4,7 @@ const VaultBaseAuth = require('./VaultBaseAuth');
 class VaultKubernetesAuth extends VaultBaseAuth {
     /**
      * @param {VaultApiClient} apiClient - see {@link VaultBaseAuth#constructor}
+     * @param {Object} logger
      * @param {Object} config
      * @param {String} config.role - Role configured in Vault Kubernetes Auth backend under which we want to issue Vault token.
      * @param {String} [config.tokenPath] - Path to the Kube JWT token. If omitted - default will be used.

package/src/auth/VaultTokenAuth.js

@@ -6,13 +6,14 @@ const errors = require('../errors');
 class VaultTokenAuth extends VaultBaseAuth {
 
     /**
-     * @param {Object} connConfig - see {@link VaultBaseAuth#constructor}
+     * @param {VaultApiClient} apiClient - see {@link VaultBaseAuth#constructor}
+     * @param {Object} logger
      * @param {Object} config
      * @param {String} config.token
-     * @param {String} mount - Vault's  mount point ("token" by default)
+     * @param {String} mount - Vault's mount point ("token" by default)
      */
-    constructor(connConfig, logger, config, mount) {
-        super(connConfig, logger, mount || 'token');
+    constructor(apiClient, logger, config, mount) {
+        super(apiClient, logger, mount || 'token');
 
         if (!config.token) {
             throw new errors.InvalidArgumentsError('Auth token should be provided for VaultTokenAuth');

package/src/errors.js

@@ -1,12 +1,12 @@
 'use strict';
 
 class VaultError extends Error {
-    constructor(message, error) {
+    constructor(message) {
         super(message);
         this.name = this.constructor.name;
         this.message = message;
 
-        Error.captureStackTrace(this, this.constructor.name);
+        Error.captureStackTrace(this, this.constructor);
     }
 }
 class InvalidArgumentsError extends VaultError {}