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

package/index.d.ts

@@ -22,7 +22,7 @@ declare class VaultClient {
 
     fillNodeConfig(): Promise<any>;
     getHeaders(token: VaultClient.AuthToken): Record<string, string>;
-    close(): void;
+    close(): Promise<void> | null | undefined;
 }
 
 declare namespace VaultClient {
@@ -103,6 +103,7 @@ declare namespace VaultClient {
         renewal?: boolean;
         renewalFraction?: number;
         renewalIncrement?: number;
+        revokeOnClose?: boolean;
     }
 
     type AuthOptions = AuthOptionsCommon &
@@ -121,7 +122,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.3.0",
   "description": "A Vault Client implemented in pure javascript for HashiCorp Vault. It supports variety of Auth Backends and performs lease renewal for issued auth token.",
   "repository": {
     "url": "git+https://github.com/namecheap/node-vault-client.git"
@@ -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;
@@ -222,7 +390,10 @@ class VaultApiClient {
                 }
 
                 if (!response.ok) {
-                    throw new errors.VaultHttpError(response.status, text, body);
+                    // headers?.: fetch test doubles in callers' suites often have no headers
+                    throw new errors.VaultHttpError(response.status, text, body, {
+                        retryAfter: response.headers?.get('retry-after'),
+                    });
                 }
 
                 // Do not log the response body: Vault responses carry secret