node-vault-client 3.0.2 → 3.2.0

package/src/VaultClient.js

@@ -16,53 +16,113 @@ const safeMessage = require('./safeMessage');
 const { trimTrailingSlashes } = require('./slashes');
 
 const noop = () => {};
-const vaultInstances = {};
-
-// Only credential providers compare by identity: a different provider means the client would
-// authenticate differently. Other functions (logger methods, an IAM `credentials` provider
-// chain) are often re-created per call with the same behaviour, so they all fingerprint alike.
-const IDENTITY_COMPARED_KEYS = new Set(['jwtProvider', 'distributedClaimAccessTokenProvider']);
+// 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:
+// structurally, any two dispatchers look alike, and so do two loggers built from different
+// functions, so a boot() that passed a different one was ignored without a warning (#224).
+// A Buffer, Date, URL or RegExp compares by value, so an equal one re-created per call still
+// matches. No user code (getters, toJSON, Proxy traps) decides the comparison.
+//
+// Per-process ids, in a WeakMap so that fingerprinting never keeps an option (or the closure
+// state it captures) alive.
+const identityIds = new WeakMap();
+let nextIdentityId = 0;
+
+function identityId(value) {
+    if (!identityIds.has(value)) {
+        identityIds.set(value, ++nextIdentityId);
+    }
+    return identityIds.get(value);
+}
 
-// Per-process ids for those providers. A WeakMap so that fingerprinting never keeps a
-// provider (or the closure state it captures) alive.
-const functionIds = new WeakMap();
-let nextFunctionId = 0;
+/**
+ * How an object takes part in the fingerprint: 'array' and 'plain' by content, 'value' by
+ * {@link valueOf}, anything else by identity. Plain includes a null prototype and an
+ * Object.prototype from another realm (vm, a test runner's structuredClone). A Proxy whose
+ * traps throw compares by identity rather than making boot() throw.
+ */
+function kindOf(value) {
+    try {
+        if (Array.isArray(value)) {
+            return 'array';
+        }
+        if (Buffer.isBuffer(value) || value instanceof Date || value instanceof URL || value instanceof RegExp) {
+            return 'value';
+        }
+        const proto = Object.getPrototypeOf(value);
+        return proto === null || Object.getPrototypeOf(proto) === null ? 'plain' : 'identity';
+    } catch {
+        return 'identity';
+    }
+}
 
-function functionId(fn) {
-    if (!functionIds.has(fn)) {
-        functionIds.set(fn, ++nextFunctionId);
+function valueOf(value) {
+    if (Buffer.isBuffer(value)) {
+        return `buffer:${value.toString('base64')}`;
+    }
+    if (value instanceof Date) {
+        return `date:${value.getTime()}`;
     }
-    return functionIds.get(fn);
+    return `${value instanceof URL ? 'url' : 'regexp'}:${JSON.stringify(String(value))}`;
 }
 
 /**
- * Order-insensitive canonical form of the boot options, hashed so that no credential is
- * retained just to compare two boot() calls. `jwtProvider` and
- * `distributedClaimAccessTokenProvider` compare by identity; every other function is `fn`.
+ * Order-insensitive canonical form of a boot option, hashed so that no credential is retained
+ * just to compare two boot() calls. Plain objects and arrays compare by content, functions and
+ * other objects by identity, and a Buffer, Date, URL or RegExp by value.
  */
-function fingerprintOptions(value, seen, key) {
+function fingerprintOptions(value, seen) {
     if (typeof value === 'function') {
-        return IDENTITY_COMPARED_KEYS.has(key) ? `fn#${functionId(value)}` : 'fn';
+        return `fn#${identityId(value)}`;
+    }
+    if (typeof value === 'bigint') {
+        return `${value}n`;
     }
     if (value === null || typeof value !== 'object') {
         return JSON.stringify(value) || String(value);
     }
+    const kind = kindOf(value);
+    if (kind === 'value') {
+        return valueOf(value);
+    }
+    if (kind === 'identity') {
+        return `obj#${identityId(value)}`;
+    }
     seen = seen || new Set();
     if (seen.has(value)) {
         return 'circular';
     }
     seen.add(value);
-    if (Array.isArray(value)) {
+    if (kind === 'array') {
         return `[${value.map((item) => fingerprintOptions(item, seen)).join(',')}]`;
     }
     const body = Object.keys(value).sort()
-        .map((key) => `${JSON.stringify(key)}:${fingerprintOptions(value[key], seen, key)}`)
+        .map((key) => `${JSON.stringify(key)}:${fingerprintOptions(value[key], seen)}`)
         .join(',');
     return `{${body}}`;
 }
 
-function optionsDigest(options) {
-    return crypto.createHash('sha256').update(fingerprintOptions(options)).digest('hex');
+/** One digest per top-level option, so a mismatch can name the options that differ. */
+function optionsDigests(options) {
+    const digests = new Map();
+    for (const key of Object.keys(options)) {
+        digests.set(key, crypto.createHash('sha256').update(fingerprintOptions(options[key])).digest('hex'));
+    }
+    return digests;
+}
+
+/** The top-level options whose digests differ, sorted; empty when the options match. */
+function differingOptions(before, after) {
+    const keys = new Set([...before.keys(), ...after.keys()]);
+    return [...keys].filter((key) => before.get(key) !== after.get(key)).sort();
 }
 
 // fetch() parses the joined URL per the WHATWG URL Standard: '?' starts the query, '#' the
@@ -133,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 {
 
     /**
@@ -140,11 +226,16 @@ 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.
+     *      `0` turns the limit off.
      * @param {Object} [options.api.kv] - KV engine options
      * @param {boolean} [options.api.kv.autoDetect=false] - When true, auto-detect KV version per mount
      * @param {Object} [options.api.engines] - Mount-to-version overrides, e.g. { secret: 2, legacy: 1 }
@@ -227,8 +318,15 @@ class VaultClient {
      * `options` are used only when the instance is first created. A later call for a name
      * that already exists returns the existing instance and ignores the options it was
      * given; when those options differ from the ones the instance was booted with, that is
-     * logged as a warning rather than passing silently. Use {@link VaultClient.get} to
-     * fetch an existing instance, or {@link VaultClient.clear} to replace one.
+     * logged as a warning, naming the top-level options that differ, rather than passing
+     * silently. The warning is logged once per instance for each set of differing options.
+     * Use {@link VaultClient.get} to fetch an existing instance, or {@link VaultClient.clear}
+     * to replace one.
+     *
+     * Options are compared as hashes, so no credential is kept for the comparison. Plain
+     * objects and arrays compare by content, in any key order. Functions and other objects (a
+     * logger class instance, an undici dispatcher) compare by identity, and a Buffer, Date,
+     * URL or RegExp by value.
      *
      * @param {String} name - Vault instance name
      * @param {Object} options - options for {@link VaultClient#constructor}. Required on
@@ -240,17 +338,26 @@ 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.__bootDigest = optionsDigest(options);
-        } else if (instance.__bootDigest !== optionsDigest(options)) {
+            instance = new VaultClient(options);
+            vaultInstances.set(instanceKey(name), instance);
+            instance.__bootDigests = optionsDigests(options);
+            instance.__bootWarned = new Set();
+            return instance;
+        }
+
+        // Once per instance for each set of differing options: code that re-creates its logger
+        // for every boot() call would otherwise log this on every call.
+        const differing = differingOptions(instance.__bootDigests, optionsDigests(options)).join(', ');
+        if (differing !== '' && !instance.__bootWarned.has(differing)) {
+            instance.__bootWarned.add(differing);
             instance.__log.warn(
                 'VaultClient.boot("%s") was called with different options than the existing ' +
                 'instance was booted with; the existing instance is returned and these options ' +
                 'are ignored. Use VaultClient.get("%s") to fetch it, or VaultClient.clear("%s") ' +
-                'first to replace it.',
-                name, name, name
+                'first to replace it. Differing options: %s.',
+                name, name, name, differing
             );
         }
         return instance;
@@ -266,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');
@@ -280,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);
         }
     }
 
@@ -306,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();
         }
@@ -396,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;
             });
+        }));
     }
 
     // -------------------------------------------------------------------------
@@ -445,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;
     }
 
     /**