node-vault-client 3.0.2 → 3.2.0

package/README.md

@@ -116,6 +116,21 @@ when Vault's `sts_region` / `sts_endpoint` is configured for a non-`us-east-1` r
 `SignatureDoesNotMatch — Credential should be scoped to a valid region`. Omitting `region`
 preserves the previous (global-endpoint) behavior.
 
+#### `iam_server_id_header_value`
+
+Set it to the same value as `iam_server_id_header_value` in the mount's `auth/<mount>/config/client`.
+The client then sends it in the signed request as `X-Vault-AWS-IAM-Server-ID`, so the signature
+names your Vault server. A Vault server that enforces its own `iam_server_id_header_value` then
+rejects a request captured from, or meant for, a different server; one that does not set the value
+checks nothing. Vault rejects a login with a missing or wrong value only when the mount sets the
+value. The header does not stop a replay to the same server while the signature is valid (about 15
+minutes).
+
+When `config.iam_server_id_header_value` is missing, empty or only whitespace, the first login
+logs one warning and logs in as before, sending the value it has. Each logger gets the warning once
+per Vault server, namespace and mount: clients on the default console logger share it, so the
+process logs it once, and a client with `logger: false` logs nothing and leaves it to the others.
+
 ### AppRole auth
 
 ```javascript
@@ -423,6 +438,27 @@ that token expires, and this client does not renew secret leases — only the au
 dynamic credentials (`database/creds/*`, cloud credentials) whose lease outlives the auth token,
 leaving renewal on is what currently keeps them alive. KV reads are unaffected.
 
+#### Tokens revoked on the Vault side
+
+A token can stop working before its expiry, for example when an operator revokes it
+(`vault token revoke`, `sys/leases/revoke-prefix`). Vault then answers 403 to every request that
+carries it. When a secret request or a mount detection gets a 403, the client asks
+`auth/token/lookup-self`, which every login already calls, whether Vault still accepts the token:
+
+* If it does, the 403 was a policy denial. The call rejects with it as before, and no login is made.
+* If it does not, the client drops the token and its renewal timer, logs `Vault no longer accepts
+  the token (accessor=…); logging in again` at `warn`, logs in, and sends the request once more.
+  The call then returns what that attempt got: its result, or its error (a failed login, a 404, a
+  timeout). Like any re-login, it replays the configured credential (see the table above).
+
+Concurrent requests rejected with the same token share one lookup and one login. A 403 on the login
+itself is returned as before. Under `token` auth there is no credential to log in with, so the 403
+is returned as before, without a lookup.
+
+So revoking a client's token no longer locks it out: it logs straight back in with the same
+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).
+
 #### Tuning renewal instead of disabling it
 
 Two further keys, also on `auth`, shape *how* renewal happens. Both are optional, and leaving them
@@ -502,9 +538,10 @@ Client constructor function.
 | --- | --- | --- | --- |
 | options | `Object` |  |  |
 | options.api | <code>Object</code> |  |  |
-| options.api.url | <code>String</code> |  | the url of the vault server |
+| options.api.url | <code>String</code> |  | the url of the vault server. Plain `http://` to a host other than this machine logs a warning; see "Plain `http://` api.url" |
 | [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.api.requestOptions] | <code>Object</code> |  | extra options merged into every HTTP request (see [Custom transport](#custom-transport-proxy--self-signed-tls)); a `redirect` there replaces the same-origin redirect policy (see [Redirects and the Vault token](#redirects-and-the-vault-token)) |
+| [options.api.timeout] | <code>number</code> | `120000` | milliseconds a request may take, response headers, body and redirects included, before it rejects with `RequestTimeoutError`; `0` turns the limit off, `null` gives the default (see [Request timeouts](#request-timeouts)) |
 | [options.api.namespace] | <code>String</code> |  | Optional. Vault namespace, sent as the `X-Vault-Namespace` header on **every** request — login, token lookup/renewal, and all secret operations — for every auth type. This is the canonical location; `auth.config.namespace` is still honored for backward compatibility. |
 | [options.api.kv.autoDetect] | <code>boolean</code> | `false` | auto-detect the KV version of each mount on first use (see [KV v2 & generic backends](#kv-v2--generic-backends)) |
 | [options.api.engines] | <code>Object</code> | `{}` | static mount-to-version map, e.g. `{ secret: 2, legacy: 1 }` (see [KV v2 & generic backends](#kv-v2--generic-backends)) |
@@ -559,8 +596,35 @@ bundle undici 7.x, so pin `undici@^7`.
 
 ##### Request timeouts
 
-There is no default timeout. A Vault that accepts the connection and never answers will leave
-`read()` (and every other call) pending indefinitely. Set one through the dispatcher:
+Every request to Vault, including logins, `lookup-self` and background `renew-self`, has to
+finish within `api.timeout` milliseconds: **120 000 (2 minutes) by default**. The limit covers the
+whole request: response headers, the body and any redirects. A request that runs out of time
+rejects with `RequestTimeoutError` (its `timeout` property holds the limit, `cause` the
+`fetch()` rejection). With `api.kv.autoDetect`, a mount detection that times out fails the call
+with the usual detection `VaultError`, with `RequestTimeoutError` on its `cause`. A renewal that
+times out is handled like any other failed renewal.
+
+`api.timeout` is in milliseconds; `null` or leaving it out gives the default, and a value under
+1000 logs a warning in case it was meant as seconds. Anything but an integer from 0 to 2147483647
+raises `InvalidArgumentsError` when the client is created.
+
+The default sits above Vault's own default `max_request_duration` (90 s), so it does not cut
+short a request that a Vault with default settings would still answer. Set it lower to fail
+fast, or higher if your Vault allows longer requests:
+
+```javascript
+const vaultClient = VaultClient.boot('main', {
+    api: { url: 'https://vault.example.com:8200/', timeout: 10000 },
+    auth: { type: 'token', config: { token: '...' } },
+});
+```
+
+`timeout: 0` turns the limit off, as it was before `api.timeout` existed. What remains then
+are the timeouts of the dispatcher `fetch()` uses: Node's default one gives up after 300 s
+without response headers (`TypeError: fetch failed`, `cause.code` `UND_ERR_HEADERS_TIMEOUT`) or
+300 s without body data (`UND_ERR_BODY_TIMEOUT`). Those limits apply per phase, so a body that
+keeps trickling in is never cut off. Any timeouts set on a custom dispatcher still apply
+alongside `api.timeout`, and whichever fires first rejects the request:
 
 ```javascript
 const { Agent } = require('undici');
@@ -574,24 +638,54 @@ const vaultClient = VaultClient.boot('main', {
 });
 ```
 
-A failed request rejects with `TypeError: fetch failed`, with `cause.code` set to
-`UND_ERR_HEADERS_TIMEOUT` or `UND_ERR_BODY_TIMEOUT`.
-
-Do **not** put `signal: AbortSignal.timeout(ms)` in `requestOptions`. It is created once and
-shared by every request the client makes, so it works for the first call and then aborts all
-later ones with `TimeoutError`. Pass a fresh signal per call, or use the dispatcher above.
+A `signal` in `requestOptions` still aborts every request in flight when it fires (with the
+signal's own reason, not `RequestTimeoutError`), so an `AbortController` can cancel requests
+on shutdown. `fetch()` then receives the client's own per-request signal, which follows it. Do **not** use `signal: AbortSignal.timeout(ms)` there: it is created once and
+shared by every request the client makes, so it works for the first calls and then aborts all
+later ones. Use `api.timeout` instead.
+
+##### Plain `http://` api.url
+
+When `api.url` is `http://` and its host is not this machine, the client logs one warning on its
+first request: `"api.url" uses plain http:// for <host:port>, which is not a loopback address; the
+Vault token and secrets travel unencrypted. …` (on port 80 the message names the bare host).
+Nothing else changes: the client connects and works as before. `localhost`, `127.0.0.0/8` (also
+as `::ffff:127.x.y.z`), `::1`, and the unspecified addresses `0.0.0.0` and `::` count as this
+machine; subdomains of `localhost` do not, since the system resolver can send them anywhere. The
+warning names only the host and port, never credentials or a path from the URL. Each logger gets
+it once per host and port: clients on the default console logger share it, so the process logs it
+once, and a client with `logger: false` logs nothing and leaves the warning to the others. If the
+logger throws, the client tries again on its next request. Only `api.url` is checked, not where a
+proxy `dispatcher` or `requestOptions.redirect: 'follow'` sends the request.
+
+If the connection is protected another way (a service mesh with mTLS, a TLS-terminating sidecar on
+another host), filter that message in your `logger`, or switch to `https://`.
 
 ##### Redirects and the Vault token
 
-Requests follow HTTP redirects, because Vault HA clusters answer standby nodes with a 307 to the
-active node. Node's `fetch()` strips only `Authorization`, `Cookie` and `Proxy-Authorization` when
-a redirect crosses origins — `X-Vault-Token` is **not** on that list and is forwarded. A 307 or 308
-also re-sends the request body, so a login is replayed to the redirect target with its credentials:
-the AppRole `secret_id`, the Kubernetes or JWT token, the signed IAM request and, with
-`distributedClaimAccessToken`, a Microsoft Graph access token that is a credential for systems other
-than Vault. A host that can answer for `api.url` can therefore redirect the client and receive its
-Vault token and its login credentials, so treat `api.url` (and the DNS and any load balancer in
-front of it) as trusted infrastructure.
+Requests follow HTTP redirects only within the origin (scheme, host and port) of `api.url`, the
+way `fetch()` follows them: up to 20 hops, a 307 or 308 re-sends the method and body, and a 303,
+or a 301 or 302 after a `POST`, becomes a `GET` without a body. A redirect to any other origin
+rejects with a `VaultError` ("Refusing to follow a redirect from … to …") and nothing is sent
+there. That includes a change of scheme on the same host: if a load balancer redirects an
+`http://` `api.url` to `https://`, use the `https://` URL. Where `fetch()` itself gives up on a
+redirect (more than 20 hops, or a `Location` that does not parse, is not http(s) or carries
+credentials), the request rejects as it always has, with `TypeError: fetch failed` and the reason
+on `cause`, so catch both if you handle redirect failures.
+
+Earlier versions followed every redirect. Node's `fetch()` strips only `Authorization`,
+`Cookie` and `Proxy-Authorization` when a redirect crosses origins, so `X-Vault-Token` went to the
+new origin, a 307 or 308 replayed a login body with its credentials (the AppRole `secret_id`, the
+Kubernetes or JWT token, the signed IAM request, a `distributedClaimAccessToken` Graph token), and
+that origin's answer was returned as Vault's.
+
+A Vault HA standby forwards requests to the active node. It answers with a 307 to the active
+node's `api_addr` only when forwarding fails or the client sends `X-Vault-No-Request-Forwarding`.
+If that address is another origin, point `api.url` at a load balancer that routes to the active
+node. A `redirect` in `api.requestOptions` (other than `null`, which reads as not set) is passed
+to `fetch()` as it is: `'follow'` restores
+the old behaviour (then treat `api.url`, its DNS and anything in front of it as trusted with the
+token), `'manual'` returns a redirect as a `VaultHttpError`, and `'error'` fails it.
 
 <a name="VaultClient+fillNodeConfig"></a>
 
@@ -788,6 +882,14 @@ discarded rather than arming a fresh timer, so the client stops holding the even
 same applies when a token is replaced by a new login — a renewal still running against the previous
 token cannot overwrite the newer one or cancel its timer.
 
+The same goes for a login that is in flight when `close()` runs, such as the first `read` of a
+client closed before it settles: the read still resolves and the token is cached for later calls,
+but no refresh timer is armed for it. A call made after `close()` that joins that same login
+shares its token and gets no timer either, just as if `close()` had run right after the login. A
+login that starts after `close()` arms one as before. As after any `close()`, the token is then
+used until it expires; under `token` auth, which cannot log in again, later calls reject with
+`AuthTokenExpiredError`, so close a client only once nothing will use it any more.
+
 <a name="Lease"></a>
 
 ### Lease
@@ -795,7 +897,7 @@ token cannot overwrite the newer one or cancel its timer.
 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.
+* `getValue(key)` ⇒ <code>\*</code> — value for a single key, as Vault returned it: usually a string, but `null`, `false`, `0`, objects and arrays come back as they are. Throws `Requested key does not exist` when the key is not an own property of the response data (for an array, such as a `list()` result, that means an index or `length`). A name such as `constructor` or `toString` counts only when Vault sent a field by that name, never as an inherited member.
 * `getData()` ⇒ <code>Object</code> — a deep-cloned copy of the whole secret data object.
 * `isRenewable()` ⇒ <code>boolean</code> — whether the underlying lease is renewable.
 * `getMetadata()` ⇒ <code>Object</code> | <code>undefined</code> — KV v2 version metadata
@@ -816,6 +918,14 @@ the ones it was booted with, the client logs a warning rather than letting the d
 silently. Use [`VaultClient.get(name)`](#VaultClient.get) to fetch an existing instance, or
 [`VaultClient.clear(name)`](#VaultClient.clear) before booting to replace one.
 
+Options are compared as hashes, so no credential is kept for the comparison. Plain objects and
+arrays compare by content, in any key order. Functions and other objects compare by identity, and
+a `Buffer`, `Date`, `URL` or `RegExp` by value. So a logger class instance, an undici `dispatcher`,
+or a logger object built from new functions counts as different even when it would behave the
+same; a plain object that reuses the same functions does not. The warning names the top-level
+options that differ (for example `logger`) and is logged once per instance for each set of them.
+Boot each name once and fetch it with `get()` elsewhere.
+
 **Kind**: static method of [<code>VaultClient</code>](#VaultClient)  
 **Returns**: <code>VaultClient</code>  
 
@@ -846,6 +956,18 @@ Clear named Vault instance
 
 If no name passed all named instances will be cleared.
 
+Only a string names one instance. Any other argument (a number, `null`, an object, a symbol)
+clears every instance not named by a symbol, as it always has. That is rarely what was meant:
+`clear(42)`, or `clear` passed as a callback that receives a code or a resolved value
+(`promise.then(VaultClient.clear)`). So the first such call in a process also emits a
+`DeprecationWarning` with code `NVC_DEP_CLEAR_NON_STRING`, naming the argument's type but not its
+value. Call `clear()` with no argument to clear every instance.
+
+Node delivers warnings on the next tick, so the warning is not shown when `clear` runs inside a
+`process.on('exit')` listener, which still clears every instance. `--no-deprecation` silences the
+warning. Under `--throw-deprecation` it becomes an uncaught exception on the next tick, not an
+error thrown by `clear()`.
+
 **Kind**: static method of [<code>VaultClient</code>](#VaultClient)  
 
 | Param | Type | Description |
@@ -1059,12 +1181,13 @@ 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. |
+| `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. |
-| `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). |
+| `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. |
 | `UnsupportedOperationError` | `VaultError` | A v2-only method (`deleteVersions`, `undeleteVersions`, `destroyVersions`, `readMetadata`, `deleteMetadata`) was called against a mount that did not resolve as KV v2. |
+| `RequestTimeoutError` | `VaultError` | A request to Vault did not finish within `api.timeout` milliseconds (see [Request timeouts](#request-timeouts)). Carries the limit as `timeout` and the `fetch()` rejection (a `TimeoutError` DOMException) as `cause`. |
 
 ## Contributing
 

package/index.d.ts

@@ -39,6 +39,8 @@ declare namespace VaultClient {
         apiVersion?: string;
         namespace?: string;
         requestOptions?: Record<string, any>;
+        /** Milliseconds a request may take before it rejects with RequestTimeoutError; `0` turns it off. Default 120000. */
+        timeout?: number | null;
         kv?: { autoDetect?: boolean };
         engines?: Record<string, 1 | 2>;
     }
@@ -119,7 +121,7 @@ declare namespace VaultClient {
     }
 
     interface Lease {
-        getValue<T = any>(key: string): T;
+        getValue<T = any>(key: string | number): T;
         getData<T = Record<string, any>>(): T;
         isRenewable(): boolean;
         getMetadata(): Record<string, any> | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-vault-client",
-  "version": "3.0.2",
+  "version": "3.2.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"
@@ -18,9 +18,10 @@
     "test": "mocha --exit \"test/**/*.test.mjs\"",
     "test:unit": "mocha \"test/*.test.mjs\"",
     "test:types": "tsc -p types/tsconfig.json",
-    "test:e2e": "mocha --exit \"test/e2e/e2e.test.mjs\"",
-    "test:e2e:kv2": "mocha --exit \"test/e2e/e2e.kv2.test.mjs\"",
-    "test:e2e:jwt": "mocha --exit \"test/e2e/e2e.jwt.test.mjs\"",
+    "test:e2e": "mocha --exit --require test/e2e/renewal-timer-guard.mjs \"test/e2e/e2e.test.mjs\"",
+    "test:e2e:kv2": "mocha --exit --require test/e2e/renewal-timer-guard.mjs \"test/e2e/e2e.kv2.test.mjs\"",
+    "test:e2e:jwt": "mocha --exit --require test/e2e/renewal-timer-guard.mjs \"test/e2e/e2e.jwt.test.mjs\"",
+    "test:e2e:generic": "mocha --exit --require test/e2e/renewal-timer-guard.mjs \"test/e2e/e2e.generic.test.mjs\"",
     "test:example": "node examples/jwt-auth/vault-jwt-demo.mjs",
     "coverage": "c8 npm run test:unit",
     "lint": "eslint src/ test/ examples/",
@@ -54,15 +55,17 @@
   },
   "overrides": {
     "serialize-javascript": "^7.1.4",
-    "glob": "^13.0.0",
+    "glob": "^14.0.3",
     "diff": "^8.0.3",
     "brace-expansion": "^5.0.12",
-    "js-yaml": "^4.3.2"
+    "js-yaml": "^4.3.2",
+    "minimatch": "^11.0.4"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "c8": "^12.0.0",
     "chai": "^6.2.2",
+    "config": "^4.4.2",
     "deep-freeze": "^0.0.1",
     "eslint": "^10.10.0",
     "globals": "^17.8.0",

package/src/Lease.js

@@ -29,15 +29,21 @@ class Lease {
     }
 
     /**
-     * @param {String} key
-     * @returns {String}
+     * @param {String|number} key - a field name, or an index when the data is an array (a list)
+     * @returns {*} the field's value as Vault returned it: a string for most secrets, but
+     *      `null`, `false`, `0`, an object or an array are returned as they are
+     * @throws {Error} 'Requested key does not exist' unless `key` is an own property of the
+     *      response data whose value is not `undefined`
      */
     getValue(key) {
-        if (this.__data[key] === undefined) {
+        const data = this.__data;
+        // Own fields only: an inherited member such as `constructor` or `__proto__` is not
+        // something Vault returned.
+        if (data === null || typeof data !== 'object' || !Object.hasOwn(data, key) || data[key] === undefined) {
             throw new Error('Requested key does not exist');
         }
 
-        return this.__data[key];
+        return data[key];
     }
 
     /**

package/src/MountResolver.js

@@ -36,6 +36,26 @@ function decodePath(path) {
     }
 }
 
+/**
+ * The error a caller gets when the detection it started or joined failed. It is built for each
+ * caller, so its message names that caller's own path rather than the first caller's. The
+ * failure stays on `cause`.
+ * safeMessage: this message is logged by the operation's catch handler, so it must not embed a
+ * raw response body.
+ *
+ * @param {Error} err - why the detection failed
+ * @param {string} interimKey - the mount the detection was keyed on
+ * @param {string} path - the caller's path
+ * @returns {VaultError}
+ */
+function detectionError(err, interimKey, path) {
+    return new VaultError(
+        `Failed to detect KV engine version for mount "${interimKey}" (path: ${path}): ${safeMessage(err)}. ` +
+        'Set api.engines or disable autoDetect to bypass detection.',
+        { cause: err }
+    );
+}
+
 /**
  * Resolves the KV engine version for a given secret path.
  *
@@ -215,6 +235,11 @@ class MountResolver {
                 // The shared detection resolved to a different mount — start our own.
                 // Use the full path as key so it won't collide with the first-segment key.
                 return this.__detectWithCache(path, path);
+            }, (err) => {
+                // A failed detection is shared, as it always was: one request, whatever it
+                // answered, so a rate limit or a failed login is not repeated per caller. Only
+                // the error is built per caller, so it names that caller's own path.
+                throw detectionError(err, interimKey, path);
             });
         }
 
@@ -255,17 +280,14 @@ class MountResolver {
             .catch((err) => {
                 // Clear in-flight so callers can retry
                 this.__inflight.delete(interimKey);
-                // safeMessage: this message is logged by the operation's catch handler, so it
-                // must not embed a raw response body; the original error stays on `cause`.
-                throw new VaultError(
-                    `Failed to detect KV engine version for mount "${interimKey}" (path: ${path}): ${safeMessage(err)}. ` +
-                    'Set api.engines or disable autoDetect to bypass detection.',
-                    { cause: err }
-                );
+                throw err;
             });
 
+        // Callers that join get the raw failure and build their own error (see above).
         this.__inflight.set(interimKey, promise);
-        return promise;
+        return promise.catch((err) => {
+            throw detectionError(err, interimKey, path);
+        });
     }
 
     /**