node-vault-client 3.1.0 → 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,9 @@ 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)) |
@@ -608,17 +644,48 @@ on shutdown. `fetch()` then receives the client's own per-request signal, which
 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>
 
@@ -815,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
@@ -822,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
@@ -881,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 |
@@ -1094,7 +1181,7 @@ 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 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. |

package/index.d.ts

@@ -121,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.1.0",
+  "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,10 +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:generic": "mocha --exit \"test/e2e/e2e.generic.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/",
@@ -65,6 +65,7 @@
     "@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);
+        });
     }
 
     /**

package/src/VaultApiClient.js

@@ -3,6 +3,7 @@
 const { defaultMaxListeners, getMaxListeners, setMaxListeners } = require('events');
 const errors = require('./errors');
 const { trimTrailingSlashes } = require('./slashes');
+const warnOnce = require('./warnOnce');
 
 // Above Vault's own default max_request_duration (90 s), so no request a default-configured
 // Vault would still answer is cut short, and below the 300 s headers/body timeouts of the
@@ -12,6 +13,11 @@ const DEFAULT_TIMEOUT_MS = 120000;
 const MAX_TIMEOUT_MS = 2147483647;
 // The listener limit fetch() gives a signal it is passed (see deadline()).
 const FETCH_MAX_LISTENERS = 1500;
+// The statuses fetch() follows, its limit on hops, and the headers it drops when a redirect
+// turns the request into a GET without a body (Fetch Standard, "HTTP-redirect fetch").
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const MAX_REDIRECTS = 20;
+const BODY_HEADERS = new Set(['content-encoding', 'content-language', 'content-location', 'content-type']);
 
 function validateTimeout(timeout) {
     // null reads as "not set", as it does in a config file.
@@ -81,6 +87,87 @@ function deadline(ms, signal) {
     };
 }
 
+function isPrintableAscii(value) {
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        if (code < 0x20 || code > 0x7e) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/**
+ * Follows the redirects of a request sent with `redirect: 'manual'` as fetch()'s 'follow'
+ * would, but only within the origin of the URL it was sent to. 'follow' sends every header
+ * but Authorization, Cookie and Proxy-Authorization to any origin a Location names, so
+ * X-Vault-Token, and on a 307/308 a login body, would reach that origin, and its answer would
+ * be read as Vault's.
+ *
+ * @param {Response} response - the answer to the request
+ * @param {string} url - the URL the request was sent to
+ * @param {Object} options - the fetch() options it was sent with
+ * @param {number} [hops=0] - redirects followed so far
+ * @returns {Response|Promise<Response>} the first answer that is not a redirect
+ */
+function followSameOrigin(response, url, options, hops = 0) {
+    let location = REDIRECT_STATUSES.has(response.status) ? response.headers.get('location') : null;
+    if (location === null) {
+        return response;
+    }
+    // A redirect's own body is never read.
+    if (response.body) {
+        response.body.cancel().catch(() => {});
+    }
+
+    // Where fetch() gives up on a redirect, it rejects with this; so does this, except for the
+    // one thing it adds: refusing another origin.
+    const fetchFailed = (cause) => new TypeError('fetch failed', { cause });
+    // As fetch() does: a Location sent as raw UTF-8 bytes instead of percent-encoded.
+    if (!isPrintableAscii(location)) {
+        location = Buffer.from(location, 'latin1').toString('utf8');
+    }
+    let next;
+    try {
+        next = new URL(location, url);
+    } catch (err) {
+        throw fetchFailed(err);
+    }
+    if (next.protocol !== 'http:' && next.protocol !== 'https:') {
+        throw fetchFailed(new TypeError('URL scheme must be a HTTP(S) scheme'));
+    }
+    if (hops === MAX_REDIRECTS) {
+        throw fetchFailed(new TypeError('redirect count exceeded'));
+    }
+    const from = new URL(url);
+    if (next.origin !== from.origin) {
+        throw new errors.VaultError(
+            `Refusing to follow a redirect from ${from.origin} to ${next.origin}: ` +
+            'only redirects within the origin of "api.url" are followed'
+        );
+    }
+    if (next.username !== '' || next.password !== '') {
+        throw fetchFailed(new TypeError('redirect location includes credentials'));
+    }
+
+    let nextOptions = options;
+    const method = options.method.toUpperCase();
+    if ((response.status === 303 && method !== 'GET' && method !== 'HEAD')
+        || ((response.status === 301 || response.status === 302) && method === 'POST')) {
+        const headers = {};
+        for (const [name, value] of Object.entries(options.headers)) {
+            if (!BODY_HEADERS.has(name.toLowerCase())) {
+                headers[name] = value;
+            }
+        }
+        nextOptions = Object.assign({}, options, { method: 'GET', headers });
+        delete nextOptions.body;
+    }
+
+    return fetch(next.href, nextOptions)
+        .then((nextResponse) => followSameOrigin(nextResponse, next.href, nextOptions, hops + 1));
+}
+
 /**
  * Joins URL segments with single slashes while preserving the leading
  * protocol (e.g. "https://"). Replaces the former `url-join` dependency.
@@ -101,6 +188,66 @@ function joinUrl(...parts) {
         .join('/');
 }
 
+/** `::ffff:127.x.y.z` as WHATWG URL prints it: `[::ffff:7fXX:XXXX]`. */
+const IPV4_MAPPED_LOOPBACK = /^\[::ffff:7f[0-9a-f]{2}:[0-9a-f]{1,4}\]$/;
+const IPV4_LOOPBACK = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+
+/**
+ * True for a host that never leaves the machine: `localhost`, 127.0.0.0/8, its IPv4-mapped IPv6
+ * form `::ffff:127.0.0.0/104`, `::1`, and the unspecified addresses `0.0.0.0` and `::`, which
+ * connect to this machine. Subdomains of `localhost` are not included: Node resolves them through
+ * the system resolver, which can send them anywhere. `hostname` is WHATWG-normalised, so IPv4
+ * shorthands such as `127.1` already read `127.0.0.1` and IPv6 is bracketed and compressed.
+ * @param {string} hostname - `URL#hostname`
+ * @returns {boolean}
+ * @private
+ */
+function isLoopbackHost(hostname) {
+    const host = hostname.endsWith('.') ? hostname.slice(0, -1) : hostname;
+    return host === 'localhost'
+        || host === '[::1]'
+        || host === '[::]'
+        || host === '0.0.0.0'
+        || IPV4_MAPPED_LOOPBACK.test(host)
+        || IPV4_LOOPBACK.test(host);
+}
+
+/**
+ * The host:port to warn about when `api.url` is plain http:// to a host off this machine (the
+ * token and every secret would cross the network unencrypted), or null. An unparsable URL gives
+ * null and is left to fail where it is used, as before.
+ * @param {*} url - `api.url`
+ * @returns {string|null}
+ * @private
+ */
+function plainHttpHost(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'http:' && !isLoopbackHost(parsed.hostname) ? parsed.host : null;
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Log the plain http:// warning for `host` unless this `logger.warn` has logged it already.
+ * Only the host and port are named, never credentials or a path from the URL.
+ * @param {string} host
+ * @param {Object} logger
+ * @returns {boolean} true once the warning is logged or was logged before; false when the
+ *      logger threw, so the caller can try again on its next request
+ * @private
+ */
+function warnOnPlainHttp(host, logger) {
+    return warnOnce(
+        logger,
+        host,
+        '"api.url" uses plain http:// for %s, which is not a loopback address; the Vault token and '
+        + 'secrets travel unencrypted. Use https:// unless the network path is protected otherwise',
+        host
+    );
+}
+
 class VaultApiClient {
 
     /**
@@ -112,7 +259,10 @@ class VaultApiClient {
      *      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.
+     *      objects such as a Dispatcher keep their prototype and remain usable. Without a
+     *      `redirect` there, redirects are followed only within the origin of `config.url`;
+     *      a `redirect` there other than `null` is passed to `fetch()` as it is (`'follow'`
+     *      follows them to any origin).
      * @param {number} [config.timeout=120000] - milliseconds a request may take, response
      *      headers, body and redirects included, before it rejects with
      *      {@link RequestTimeoutError}. `0` turns the limit off; `null` gives the default.
@@ -142,11 +292,18 @@ class VaultApiClient {
             logger.warn('"api.timeout" is %d ms; it is in milliseconds, not seconds', this.__timeout);
         }
 
+        // Logged on the first request rather than here, so a VaultClient whose construction
+        // fails after building this client logs nothing.
+        this.__plainHttpHost = plainHttpHost(this.__config.url);
+
         this.__namespace = namespace !== undefined ? namespace : this.__config.namespace;
         this._logger = logger;
     }
 
     makeRequest(method, path, data, headers) {
+        if (this.__plainHttpHost !== null && warnOnPlainHttp(this.__plainHttpHost, this._logger)) {
+            this.__plainHttpHost = null;
+        }
         data = data === undefined ? null : data;
         headers = headers === undefined ? {} : headers;
 
@@ -160,7 +317,7 @@ class VaultApiClient {
         const namespaceHeader = this.__namespace ? { 'X-Vault-Namespace': this.__namespace } : {};
 
         const options = Object.assign(
-            { redirect: 'follow' },
+            {},
             requestOptions,
             {
                 method: method,
@@ -172,6 +329,13 @@ class VaultApiClient {
                 ),
             }
         );
+        // Read after the merge, which copies only own enumerable keys: a `redirect` it leaves
+        // out, or an explicit `redirect: undefined`, must not turn fetch()'s 'follow' back on.
+        // null reads as "not set", as it does for api.timeout (fetch() rejected it).
+        const sameOrigin = options.redirect === undefined || options.redirect === null;
+        if (sameOrigin) {
+            options.redirect = 'manual';
+        }
         if (data !== null) {
             options.body = JSON.stringify(data);
             // Only set the default content-type if the caller did not already supply one.
@@ -210,6 +374,10 @@ class VaultApiClient {
             }
         }
 
+        if (sameOrigin) {
+            pending = pending.then((response) => followSameOrigin(response, uri, options));
+        }
+
         const request = pending.then((response) => {
             return response.text().then((text) => {
                 let body;

package/src/VaultClient.js

@@ -16,7 +16,13 @@ const safeMessage = require('./safeMessage');
 const { trimTrailingSlashes } = require('./slashes');
 
 const noop = () => {};
-const vaultInstances = {};
+// Named instances. A Map, so a name such as "toString" or "constructor" is not found on
+// Object.prototype; keyed exactly as an object property would be, so boot(1) and get('1') still
+// meet and an object that converts to a symbol is keyed by that symbol.
+const vaultInstances = new Map();
+const instanceKey = (name) => Reflect.ownKeys({ [name]: undefined })[0];
+// clear(name) with a non-string name warns once per process (#239); see VaultClient.clear().
+let warnedClearNonString = false;
 
 // Functions, and objects that are not plain data (an undici dispatcher, a logger class
 // instance), compare by identity. Their own enumerable keys say nothing about what they do:
@@ -187,6 +193,32 @@ function assertSafeKvPath(path, allowTrailingSlash) {
     return trimmed;
 }
 
+/**
+ * clear() with a name that is not a string closes every instance, which is rarely what the
+ * caller meant (#239): `clear(42)`, or `clear` passed as a callback that receives an exit code
+ * or a resolved value. The behaviour stays as it was; this makes it visible, once per process.
+ * It names only the argument's type, never its value, which could be anything (#239).
+ * Node delivers warnings on the next tick, so one emitted from an 'exit' listener is never shown;
+ * --no-deprecation silences it, as for any DeprecationWarning.
+ * @param {*} name
+ * @returns {void}
+ * @private
+ */
+function warnClearNonString(name) {
+    if (warnedClearNonString) {
+        return;
+    }
+    warnedClearNonString = true;
+    const type = typeof name;
+    const what = name === null ? 'null' : (type === 'object' ? 'an object' : `a ${type}`);
+    process.emitWarning(
+        `VaultClient.clear() was called with ${what} ` +
+        'instead of a string name, which clears every instance not named by a symbol, as it always ' +
+        'has. Call clear() with no argument to clear them all, or pass the string name of one instance.',
+        { type: 'DeprecationWarning', code: 'NVC_DEP_CLEAR_NON_STRING' }
+    );
+}
+
 class VaultClient {
 
     /**
@@ -194,10 +226,12 @@ class VaultClient {
      *
      * @param {Object} options
      * @param {Object} options.api
-     * @param {String} options.api.url - the url of the vault server
+     * @param {String} options.api.url - the url of the vault server. Plain `http://` to a host
+     *      other than this machine logs a warning; see "Plain `http://` api.url" in the README
      * @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).
+     *      Redirects are followed only within the origin of `api.url` unless it sets `redirect`.
      *      See {@link VaultApiClient#constructor}.
      * @param {number} [options.api.timeout=120000] - milliseconds a request may take, response
      *      headers, body and redirects included, before it rejects with RequestTimeoutError.
@@ -304,9 +338,10 @@ class VaultClient {
             throw new errors.InvalidArgumentsError('Options should be provided');
         }
 
-        let instance = vaultInstances[name];
+        let instance = vaultInstances.get(instanceKey(name));
         if (instance === undefined) {
-            vaultInstances[name] = instance = new VaultClient(options);
+            instance = new VaultClient(options);
+            vaultInstances.set(instanceKey(name), instance);
             instance.__bootDigests = optionsDigests(options);
             instance.__bootWarned = new Set();
             return instance;
@@ -338,7 +373,7 @@ class VaultClient {
      * @return {VaultClient}
      */
     static get(name) {
-        let instance = vaultInstances[name];
+        let instance = vaultInstances.get(instanceKey(name));
 
         if (instance === undefined) {
             throw new errors.InvalidArgumentsError('Invalid instance name');
@@ -352,22 +387,33 @@ class VaultClient {
      *
      * If no name passed all named instances will be cleared.
      *
+     * Only a string names one instance. Any other argument (a number, `null`, an object) clears
+     * every instance, as it always has, and emits a one-time `DeprecationWarning`
+     * (`NVC_DEP_CLEAR_NON_STRING`): call `clear()` with no argument to clear them all.
+     *
      * @param {String} [name] - Vault instance name, all instances will be cleared if no name were passed
      */
     static clear(name) {
         if (typeof name === 'string') {
-            const instance = vaultInstances[name];
+            const instance = vaultInstances.get(name);
             if (instance !== undefined) {
                 instance.close();
-                delete vaultInstances[name];
+                vaultInstances.delete(name);
             }
-        } else {
-            for (let k in vaultInstances) {
-                if (Object.hasOwn(vaultInstances, k)) {
-                    vaultInstances[k].close();
-                    delete vaultInstances[k];
-                }
+            return;
+        }
+        if (name !== undefined) {
+            warnClearNonString(name);
+        }
+        for (const [key, instance] of vaultInstances) {
+            // Kept for compatibility: the object this replaced was walked with for...in,
+            // which skips symbol keys, so a symbol-named instance has always stayed
+            // registered, with its renewal timer, through clear(), and callers may rely on it.
+            if (typeof key === 'symbol') {
+                continue;
             }
+            instance.close();
+            vaultInstances.delete(key);
         }
     }
 
@@ -378,11 +424,17 @@ class VaultClient {
      * 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.
+     * the next operation that fetches a renewable token will arm a new refresh timer. A
+     * 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}
      */
     close() {
+        if (this.__auth && typeof this.__auth.__markClosed === 'function') {
+            // Directly as well: a subclass may override cancelTokenRefresh() without super.
+            this.__auth.__markClosed();
+        }
         if (this.__auth && typeof this.__auth.cancelTokenRefresh === 'function') {
             this.__auth.cancelTokenRefresh();
         }
@@ -468,11 +520,39 @@ class VaultClient {
      * @private
      */
     __detectMount(path) {
-        return this.__auth.getAuthToken()
-            .then((token) => {
-                const detectPath = `sys/internal/ui/mounts/${path}`;
-                return this.__api.makeRequest('GET', detectPath, null, this.getHeaders(token));
+        return this.__withAuthToken((token) => {
+            const detectPath = `sys/internal/ui/mounts/${path}`;
+            return this.__api.makeRequest('GET', detectPath, null, this.getHeaders(token));
+        });
+    }
+
+    /**
+     * Calls `send` with the current auth token. When Vault answers 403 and the token turns out
+     * to be one Vault no longer accepts (revoked server-side), logs in again and calls `send`
+     * once more; see {@link VaultBaseAuth#checkRejectedToken}. A policy denial and a 403 under
+     * `token` auth surface that 403; otherwise the retry's own result or error is returned.
+     *
+     * @param {function(AuthToken): Promise<*>} send
+     * @returns {Promise<*>}
+     * @private
+     */
+    __withAuthToken(send) {
+        return this.__auth.getAuthToken().then((token) => send(token).catch((err) => {
+            if (!(err instanceof errors.VaultHttpError) || err.statusCode !== 403
+                    || typeof this.__auth.checkRejectedToken !== 'function') {
+                throw err;
+            }
+            return this.__auth.checkRejectedToken(token).then((retry) => {
+                if (!retry) {
+                    throw err;
+                }
+                // What the retry got, success or failure, is the request's outcome now: a login
+                // that fails, a 404 or a timeout says more than the 403 of a token already gone.
+                return this.__auth.getAuthToken().then(send);
+            }, () => {
+                throw err;
             });
+        }));
     }
 
     // -------------------------------------------------------------------------
@@ -517,50 +597,49 @@ class VaultClient {
             }
         }
 
-        return this.__auth.getAuthToken()
-            .then((token) => {
-                const headers = Object.assign({}, this.getHeaders(token), extraHeaders || {});
+        return this.__withAuthToken((token) => {
+            const headers = Object.assign({}, this.getHeaders(token), extraHeaders || {});
 
-                if (raw) {
-                    return this.__api.makeRequest(method, path, data, headers)
-                        .then((body) => ({ body, version: undefined, mount: undefined, apiPath: path }));
-                }
+            if (raw) {
+                return this.__api.makeRequest(method, path, data, headers)
+                    .then((body) => ({ body, version: undefined, mount: undefined, apiPath: path }));
+            }
 
-                return this.__resolver.resolve(path)
-                    .then(({ mount, version }) => {
-                        if (v2Only && version !== 2) {
-                            throw new errors.UnsupportedOperationError(
-                                `Operation "${op}" is only supported on KV v2 mounts. ` +
-                                `Mount "${mount}" is not a KV v2 engine.`
-                            );
-                        }
-
-                        let apiPath;
-                        if (version === 2) {
-                            // Split the path into mount + logical sub-path and rewrite for KV v2
-                            const logicalPath = this.__logicalPath(path, mount);
-                            apiPath = rewritePath(version, op, mount, logicalPath);
-                        } else {
-                            // v1 / disabled: preserve the caller's literal path byte-for-byte,
-                            // including any trailing slash, to maintain the old wire behavior.
-                            apiPath = path;
-                        }
-
-                        // Data envelope: wrapData forces { data } on every engine version
-                        // (merge-patch update() semantics — v1 mounts reject PATCH anyway);
-                        // otherwise only v2 write/update wrap non-null data.
-                        let requestData = data;
-                        if (wrapData) {
-                            requestData = { data };
-                        } else if (version === 2 && (op === 'write' || op === 'update')
-                                && data !== null && data !== undefined) {
-                            requestData = { data };
-                        }
-
-                        return this.__api.makeRequest(method, apiPath, requestData, headers)
-                            .then((body) => ({ body, version, mount, apiPath }));
-                    });
-            });
+            return this.__resolver.resolve(path)
+                .then(({ mount, version }) => {
+                    if (v2Only && version !== 2) {
+                        throw new errors.UnsupportedOperationError(
+                            `Operation "${op}" is only supported on KV v2 mounts. ` +
+                            `Mount "${mount}" is not a KV v2 engine.`
+                        );
+                    }
+
+                    let apiPath;
+                    if (version === 2) {
+                        // Split the path into mount + logical sub-path and rewrite for KV v2
+                        const logicalPath = this.__logicalPath(path, mount);
+                        apiPath = rewritePath(version, op, mount, logicalPath);
+                    } else {
+                        // v1 / disabled: preserve the caller's literal path byte-for-byte,
+                        // including any trailing slash, to maintain the old wire behavior.
+                        apiPath = path;
+                    }
+
+                    // Data envelope: wrapData forces { data } on every engine version
+                    // (merge-patch update() semantics — v1 mounts reject PATCH anyway);
+                    // otherwise only v2 write/update wrap non-null data.
+                    let requestData = data;
+                    if (wrapData) {
+                        requestData = { data };
+                    } else if (version === 2 && (op === 'write' || op === 'update')
+                            && data !== null && data !== undefined) {
+                        requestData = { data };
+                    }
+
+                    return this.__api.makeRequest(method, apiPath, requestData, headers)
+                        .then((body) => ({ body, version, mount, apiPath }));
+                });
+        });
     }
 
     /**

package/src/auth/AuthToken.js

@@ -56,19 +56,25 @@ class AuthToken {
         const hasPreciseExpiry = unadjustedExpiresAtMilliseconds !== null;
         const expiresAtMilliseconds = AuthToken.__resolveExpiresAtMilliseconds(data, unadjustedExpiresAtMilliseconds);
 
-        return new AuthToken(
+        const renewable = data.renewable !== undefined ? data.renewable : false;
+        const authToken = new AuthToken(
             data.id,
             data.accessor,
             data.creation_time,
             null,
             data.explicit_max_ttl,
             data.num_uses,
-            data.renewable !== undefined ? data.renewable : false,
+            renewable,
             expiresAtMilliseconds,
             data.ttl,
             hasPreciseExpiry,
             unadjustedExpiresAtMilliseconds
         );
+        // Without an expiry the token is not renewable. Remember that Vault said it was, so the
+        // renewal timer can say why it stops (VaultBaseAuth); a ttl of 0 means it never expires.
+        authToken.__renewableWithoutExpiry = Boolean(renewable) && data.ttl !== 0
+            && expiresAtMilliseconds === null;
+        return authToken;
     }
 
     /**
@@ -85,7 +91,8 @@ class AuthToken {
      * @private
      * @param {Object} data - the `data` object of a token lookup response
      * @param {number|null} expireTime - parsed Vault expiry in milliseconds
-     * @returns {int|null} client expiry in milliseconds, or null when ttl is 0 without expire_time
+     * @returns {int|null} client expiry in milliseconds, or null when there is none to use: ttl 0
+     *      without expire_time, or neither expire_time nor a numeric ttl and creation time
      */
     static __resolveExpiresAtMilliseconds(data, expireTime) {
         const networkLatency = 60;
@@ -106,7 +113,9 @@ class AuthToken {
         // 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)) * 1000;
+        const expiresAt = (creationTime + parseInt(ttl, 10)) * 1000;
+        // A missing ttl or creation time made this NaN, a deadline that never passes.
+        return Number.isFinite(expiresAt) ? expiresAt : null;
     }
 
     /**

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,19 @@ 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;
     }
 
     /**
@@ -252,12 +276,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 +299,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 +327,7 @@ class VaultBaseAuth {
      * @returns {void}
      */
     cancelTokenRefresh() {
+        this.__markClosed();
         this.__renewalEpoch++;
         if (this.__refreshTimeout !== null) {
             lt.clearTimeout(this.__refreshTimeout);
@@ -300,6 +335,87 @@ 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++;
+    }
+
+    /**
+     * 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 (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 +437,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 +451,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 +482,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/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;