node-vault-client 2.1.2 → 2.3.0

package/README.md

@@ -18,6 +18,45 @@ npm install --save node-vault-client
 
 Node.js >= 18 — the client uses the native `fetch` API.
 
+> **Node.js 18 sunset notice:** this is the last release of node-vault-client to support Node 18.
+> Node 18 reached end-of-life on 2025-04-30 and no longer receives security patches from the
+> Node.js project. Running this version under Node 18 emits a one-time process warning
+> (`NodeVaultClientNode18Deprecation`); the next major release raises the minimum to
+> Node.js >= 20.19.0. See [CHANGELOG.md](CHANGELOG.md) for details.
+
+### TypeScript
+
+Type declarations ship with the package, so no separate install is needed:
+
+```typescript
+import VaultClient = require('node-vault-client');
+
+const client = new VaultClient({
+    api: { url: 'http://127.0.0.1:8200' },
+    auth: { type: 'appRole', config: { role_id: 'roleId', secret_id: 'secretId' } },
+});
+
+const lease = await client.read('secret/app');
+const password = lease.getValue<string>('password');
+```
+
+`auth` is a discriminated union on `type`, so each backend only accepts its own
+configuration, and the three mutually-exclusive JWT sources (`jwt`, `jwtPath`,
+`jwtProvider`) are enforced at compile time — as is the mutually-exclusive pair
+`distributedClaimAccessToken` / `distributedClaimAccessTokenProvider`.
+
+Types that appear in signatures are exported in type space under the `VaultClient`
+namespace — `VaultClient.Lease`, `VaultClient.VaultOptions`, `VaultClient.AuthToken`
+and the per-backend config interfaces. They are types only; the classes behind them
+are not exported at runtime.
+
+If you previously installed the third-party `@types/node-vault-client`, remove it —
+it stops at the 1.x API and its declarations take precedence in some setups:
+
+```
+npm uninstall @types/node-vault-client
+```
+
 ## Example
 
 ```javascript
@@ -26,7 +65,7 @@ const VaultClient = require('node-vault-client');
 const vaultClient = VaultClient.boot('main', {
     api: { url: 'https://vault.example.com:8200/' },
     auth: { 
-        type: 'appRole', // one of: 'appRole' | 'token' | 'iam' | 'kubernetes'
+        type: 'appRole', // one of: 'appRole' | 'token' | 'iam' | 'kubernetes' | 'jwt'
         config: { role_id: '637c065f-c644-5e12-d3d1-e9fa4363af61' } 
     },
 });
@@ -42,6 +81,7 @@ vaultClient.read('secret/tst').then(lease => {
 * [AppRole](https://developer.hashicorp.com/vault/docs/auth/approle)
 * [Token](https://developer.hashicorp.com/vault/docs/auth/token)
 * [Kubernetes](https://developer.hashicorp.com/vault/docs/auth/kubernetes)
+* [JWT](https://developer.hashicorp.com/vault/docs/auth/jwt)
 
 ### AWS IAM auth
 
@@ -125,6 +165,261 @@ const vaultClient = VaultClient.boot('main', {
 });
 ```
 
+### JWT auth
+
+```javascript
+const vaultClient = VaultClient.boot('main', {
+    api: { url: 'https://vault.example.com:8200/' },
+    auth: {
+        type: 'jwt',
+        mount: 'jwt',                                  // Optional. Vault JWT auth mount point ("jwt" by default)
+        config: {
+            role: 'my-app',                                       // Optional. Role configured in Vault's JWT auth backend; omitted uses the mount's `default_role`
+            jwt: process.env.CI_JOB_JWT,                          // Exactly one of `jwt` / `jwtPath` / `jwtProvider` is required (see below)
+            distributedClaimAccessToken: process.env.GRAPH_TOKEN, // Optional. Azure/Entra ID group lookups only (see below); or `distributedClaimAccessTokenProvider`
+        },
+    },
+});
+```
+
+Exactly one of three mutually exclusive `config` keys supplies the JWT:
+
+* **`jwt`** — a literal token string. Use it for CI jobs and other processes that are guaranteed
+  to finish before the token expires. Caveat: the value is fixed at construction, so if the
+  client re-authenticates (its Vault-issued token TTL runs out while the process is still up) it
+  re-sends that exact same JWT — which works only until the IdP-issued token itself expires,
+  after which Vault rejects every further login attempt. Do not use `jwt` in a long-running
+  process.
+* **`jwtPath`** — path to a file containing the JWT, re-read on every login (mirrors
+  [Kubernetes auth](#kubernetes-auth)'s `tokenPath`). Use it for rotated *projected* tokens, such
+  as a Kubernetes projected service-account token the kubelet refreshes on disk, so each login
+  picks up whatever is currently on disk instead of a token captured once at startup.
+* **`jwtProvider`** — an (optionally async) function, called fresh at login time (never at
+  construction, never cached), returning `string | Promise<string>`. Use it when the JWT has to
+  be minted per login — GitHub Actions' `core.getIDToken()`, a cloud metadata endpoint, a
+  SPIFFE/SPIRE workload API.
+
+##### The Vault role needs `bound_audiences` when your JWT carries an `aud` claim
+
+This is server-side configuration rather than a client option, but it is the most common reason a
+first login fails. Vault requires a `jwt` role to bind the audience your token carries, and it does
+**not** catch the omission when the role is created — as long as the role has some other bound
+constraint (`bound_subject`, `bound_claims`, ...) it is accepted, and the problem only surfaces at
+login:
+
+```
+VaultHttpError: 400 - {"errors":["audience claim found in JWT but no audiences bound to the role"]}
+```
+
+A wrong (rather than missing) audience fails with `error validating token: invalid audience (aud)
+claim: audience claim does not match any expected audience`. So bind the audience the token
+actually has:
+
+```shell
+vault write auth/jwt/role/my-app \
+    role_type=jwt user_claim=sub bound_audiences=my-audience token_policies=my-policy
+```
+
+A role with *no* bound constraint at all is rejected when you create it (`must have at least one
+bound constraint when creating/updating a role`), so that case is self-correcting. An `aud` array
+is fine — Vault matches `bound_audiences` against any entry.
+
+Vault also does not require an `exp` claim: a token minted without one is accepted and never
+expires. If you write your own `jwtProvider`, give the tokens it mints a short `exp`.
+
+##### Azure / Entra ID group lookups need `distributedClaimAccessToken`
+
+Skip this unless you log in with Microsoft Entra ID (Azure AD) tokens *and* the Vault role sets
+`groups_claim`. Vault's `distributed_claim_access_token` parameter
+["only applies to the Azure (Entra ID) provider"](https://developer.hashicorp.com/vault/api-docs/auth/jwt#distributed_claim_access_token);
+on every other IdP these two keys do nothing at all.
+
+Azure does not always put group membership in the token. Past 200 groups it sends OIDC
+[distributed claims](https://openid.net/specs/openid-connect-core-1_0.html#AggregatedDistributedClaims)
+instead — `_claim_names`/`_claim_sources` pointing at the Microsoft Graph API rather than the group
+names themselves — and a mount configured with `fetch_groups` skips the claim entirely and always
+asks Graph. Either way Vault has to call Graph itself, and the JWT you logged in with is not a
+credential for that call: it needs a separate Graph access token, sent on the login request as the
+optional `distributed_claim_access_token`. Leave it out on a mount/role set up this way and the
+login fails at the group-fetch step — *after* the JWT has already validated, so the error names the
+group lookup rather than anything about your token.
+
+Two optional, mutually exclusive `config` keys supply it. Passing both raises
+`InvalidArgumentsError` at construction; passing neither leaves the login request byte-for-byte
+what it was before these keys existed.
+
+* **`distributedClaimAccessToken`** — a literal Graph access token. It carries exactly the caveat
+  the literal `jwt` above does, for the same reason: the value is fixed at construction and every
+  re-login re-sends it, so it works until that token expires. Entra access tokens last about an
+  hour, which is shorter than most processes — fine for a one-shot script, wrong for a service.
+* **`distributedClaimAccessTokenProvider`** — an (optionally async) function, called fresh at login
+  time (never at construction, never cached), returning `string | Promise<string>`. Acquire the
+  Graph token inside it — an MSAL client-credentials call, the Azure IMDS managed-identity endpoint
+  — and every login gets a current one. Resolving to a non-string or an empty string raises
+  `InvalidArgumentsError` without sending a login request.
+
+```javascript
+const vaultClient = VaultClient.boot('main', {
+    api: { url: 'https://vault.example.com:8200/' },
+    auth: {
+        type: 'jwt',
+        config: {
+            role: 'my-app',
+            jwtProvider: () => getEntraIdToken(),
+            distributedClaimAccessTokenProvider: () => getGraphAccessToken(),
+        },
+    },
+});
+```
+
+On the Vault side, `fetch_groups` lives in `provider_config` on the **mount's config, not on the
+role** — which is where people tend to look for it:
+
+```shell
+vault write auth/jwt/config \
+    oidc_discovery_url=https://login.microsoftonline.com/<tenant-id>/v2.0 \
+    provider_config='{"provider":"azure","fetch_groups":true}'
+
+vault write auth/jwt/role/my-app \
+    role_type=jwt user_claim=sub bound_audiences=<application-client-id> \
+    groups_claim=groups token_policies=my-policy
+```
+
+`fetch_groups` is optional — the distributed-claim path is taken without it whenever Azure omits
+the groups claim. `groups_claim` on the role is not: with it unset Vault never resolves groups at
+all, so a Graph token you pass is accepted and never used.
+
+#### Authenticating from GitHub Actions
+
+```yaml
+permissions:
+  id-token: write
+```
+
+```javascript
+const core = require('@actions/core');
+const VaultClient = require('node-vault-client');
+
+const vaultClient = VaultClient.boot('ci', {
+    api: { url: process.env.VAULT_ADDR },
+    auth: {
+        type: 'jwt',
+        mount: 'gha',                                  // matches wherever the JWT method was mounted, e.g. `vault auth enable -path=gha jwt`
+        config: { role: 'ci', jwtProvider: () => core.getIDToken('vault') },
+    },
+});
+```
+
+`core.getIDToken('vault')` mints a token whose `aud` is `vault`, so the role has to bind that
+audience or the login fails with `audience claim found in JWT but no audiences bound to the role`:
+
+```shell
+vault write auth/gha/role/ci \
+    role_type=jwt user_claim=sub bound_audiences=vault \
+    bound_claims='{"repository":"my-org/my-repo"}' token_policies=ci
+```
+
+Pass the same string to `core.getIDToken()` and to `bound_audiences`. Calling `getIDToken()` with
+no argument uses GitHub's default audience instead, which then will not match.
+
+`role` is optional here too — omit it to use the mount's `default_role`. `mount` and
+`api.namespace` behave exactly as they do for the other four backends.
+
+Vault's JWT method also offers an interactive `oidc` login (a browser redirect for a human user).
+This library implements only the non-interactive `jwt` flow: a service client doing headless
+background renewal has no browser to redirect to, so `oidc` is deliberately not supported.
+
+### Token renewal
+
+Whenever Vault issues a **renewable** token, the client arms a background timer and renews it at
+half its remaining lifetime, for as long as the client lives. That is the default and suits
+long-running services.
+
+Set `renewal: false` on the `auth` block (beside `type`, not inside `config`) to turn it off:
+
+```javascript
+auth: {
+    type: 'appRole',
+    renewal: false,
+    config: {
+        role_id: '637c065f-...',
+        secret_id: '...',
+    },
+}
+```
+
+These keys sit on `auth` rather than in `auth.config` on purpose: `config` is the backend's own
+credential bag and may already carry keys of your own, so reserving names inside it could break an
+existing caller. Same reasoning that put the namespace at `api.namespace`.
+
+With renewal off, the client keeps using the token until it expires and then simply logs in again
+on the next call — no background timer at all. Two reasons to want that:
+
+* **Short-lived processes.** The renewal timer keeps the Node.js event loop alive, so a script that
+  finishes its work does not exit on its own; you have to call
+  [`close()`](#VaultClient+close). With `renewal: false` there is no timer to hold it open.
+* **You would rather re-authenticate than renew** — for example where the auth backend can always
+  mint a fresh token (`jwtProvider`, Kubernetes, IAM) and you prefer a clean login over extending
+  an existing lease.
+
+#### Before you turn it off
+
+Renewal off means the token is allowed to expire, and what happens next depends on whether your
+backend can obtain a *fresh* credential unaided:
+
+| backend | on expiry with `renewal: false` |
+| --- | --- |
+| `kubernetes`, `iam`, `jwt` with `jwtPath`/`jwtProvider` | clean re-login — the JWT or AWS credential is re-acquired, so this is the intended case |
+| `appRole` | re-login **replays the same `secret_id`**. Fine for a reusable one; with Vault's recommended hardening (`secret_id_num_uses=1`, or a short `secret_id_ttl`) the second login is rejected |
+| `jwt` with a literal `jwt` | replays the same JWT, so it works only until the IdP-issued token expires |
+| `token` | **cannot re-authenticate at all.** The client raises `AuthTokenExpiredError` from then on, permanently |
+
+Two consequences worth stating plainly:
+
+* For `token` auth this **is** a behaviour change, not a no-op. A renewable token handed to `token`
+  auth is renewed indefinitely today; with `renewal: false` it expires and every later call rejects
+  for the life of the process. `close()` does not reset it — recovery means
+  `VaultClient.clear(name)` and booting again.
+* For `appRole` and literal-`jwt`, a login that can no longer succeed is retried on **every**
+  subsequent call, since a failed login clears the cached token. That is a failing request per
+  `read()`, with no backoff. Prefer `jwtPath`/`jwtProvider`, a reusable `secret_id`, or leaving
+  renewal on.
+
+**Expiring a token also revokes its leases.** Vault revokes every lease created by a token when
+that token expires, and this client does not renew secret leases — only the auth token. If you read
+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.
+
+#### Tuning renewal instead of disabling it
+
+Two further keys, also on `auth`, shape *how* renewal happens. Both are optional, and leaving them
+out reproduces the behaviour the client has always had.
+
+| key | default | meaning |
+| --- | --- | --- |
+| `renewalFraction` | `0.5` | How much of the token's **remaining** lifetime to wait before renewing, as a fraction in `(0, 1)`. `0.5` renews at the halfway point. |
+| `renewalIncrement` | *(unset)* | Seconds of extra TTL to ask for, sent as `increment` to `auth/token/renew-self`. Unset means Vault applies the token's own period. |
+
+```javascript
+auth: {
+    type: 'kubernetes',
+    renewalFraction: 0.25,   // renew after a quarter of the remaining lifetime
+    renewalIncrement: 3600,  // ask Vault for another hour each time
+    config: { role: 'my-app' },
+}
+```
+
+Lower `renewalFraction` values renew earlier and more often, which buys headroom if Vault is briefly
+unreachable. A failed renewal is retried on the same rule against the *same* token, so the waits
+shrink geometrically as the remaining lifetime does — for a 1-hour token that is roughly 12 attempts
+at `0.5` (1800s, 900s, 450s, …) versus 27 at `0.25`, both bottoming out at a 1-second floor just
+before expiry. Higher values renew later and talk to Vault less.
+
+`renewalIncrement` is a request, not a guarantee: Vault grants at most the token's max TTL and may
+return less. Both keys are validated at construction — a `renewalFraction` outside `(0, 1)` or a
+non-positive/non-integer `renewalIncrement` raises `InvalidArgumentsError` rather than failing later
+inside a background timer.
+
 ## API
 
 <a name="VaultClient"></a>
@@ -148,7 +443,7 @@ const vaultClient = VaultClient.boot('main', {
         * [.deleteMetadata(path)](#VaultClient+deleteMetadata) ⇒ <code>Promise.&lt;Object&gt;</code>
         * [.close()](#VaultClient+close)
     * _static_
-        * [.boot(name, [options])](#VaultClient.boot) ⇒ <code>VaultClient</code>
+        * [.boot(name, options)](#VaultClient.boot) ⇒ <code>VaultClient</code>
         * [.get(name)](#VaultClient.get) ⇒ <code>VaultClient</code>
         * [.clear([name])](#VaultClient.clear)
 * [Lease](#Lease)
@@ -175,11 +470,14 @@ Client constructor function.
 | [options.api.kv.autoDetect] | <code>boolean</code> | `false` | auto-detect the KV version of each mount on first use (see [KV v2 & generic backends](#kv-v2--generic-backends)) |
 | [options.api.engines] | <code>Object</code> | `{}` | static mount-to-version map, e.g. `{ secret: 2, legacy: 1 }` (see [KV v2 & generic backends](#kv-v2--generic-backends)) |
 | options.auth | <code>Object</code> |  |  |
-| options.auth.type | <code>String</code> |  |  |
-| [options.auth.mount] | <code>String</code> |  | Vault auth backend mount point; default varies per method (e.g. "aws" for iam, "approle", "token", "kubernetes") |
+| options.auth.type | <code>String</code> |  | one of: 'appRole' \| 'token' \| 'iam' \| 'kubernetes' \| 'jwt' |
+| [options.auth.mount] | <code>String</code> |  | Vault auth backend mount point; default varies per method (e.g. "aws" for iam, "approle", "token", "kubernetes", "jwt") |
 | options.auth.config | <code>Object</code> |  | auth configuration variables |
 | [options.auth.config.namespace] | <code>String</code> |  | Optional. Legacy location for the Vault namespace (see `api.namespace`). Sent as the `X-Vault-Namespace` header on **every** request for every auth type. |
-| [options.logger] | <code>Object</code> \| <code>false</code> |  | Logger that supports "error", "info", "warn", "trace", "debug" methods. Uses `console` by default. Pass `false` to disable logging. |
+| [options.auth.renewal] | <code>boolean</code> | <code>true</code> | Set `false` to never renew the Vault token in the background; the token is used until it expires and the next call re-authenticates. See [Token renewal](#token-renewal). |
+| [options.auth.renewalFraction] | <code>number</code> | <code>0.5</code> | How much of the token's remaining lifetime to wait before renewing, as a fraction in `(0, 1)`. |
+| [options.auth.renewalIncrement] | <code>number</code> |  | Seconds of extra TTL to request on each renewal, sent as `increment` to `auth/token/renew-self`. Vault caps it at the token's max TTL. |
+| [options.logger] | <code>Object</code> \| <code>false</code> |  | Logger that must implement **all five** of "error", "warn", "info", "debug" and "trace" — an object missing any one of them is silently ignored and the default logger is used instead. The default logger writes to `console`, except `debug`, which is discarded so that sensitive data is never printed. Pass `false` to disable logging entirely. |
 
 ##### Custom transport (proxy / self-signed TLS)
 
@@ -214,12 +512,50 @@ env var with no code change. Only disable verification
 (`new Agent({ connect: { rejectUnauthorized: false } })`) in throwaway/dev setups — it removes
 MITM protection.
 
+The `undici` you install must be interface-compatible with the one Node bundles
+(`process.versions.undici`). A dispatcher from a mismatched major is rejected by the global
+`fetch()` before the request leaves the process — on Node 24, `undici@8` fails immediately with
+`TypeError: fetch failed` and `cause.code` of `invalid onRequestStart method`. Node 22 and 24
+bundle undici 7.x, so pin `undici@^7`.
+
+##### Request timeouts
+
+There is no default timeout. A Vault that accepts the connection and never answers will leave
+`read()` (and every other call) pending indefinitely. Set one through the dispatcher:
+
+```javascript
+const { Agent } = require('undici');
+
+const vaultClient = VaultClient.boot('main', {
+    api: {
+        url: 'https://vault.example.com:8200/',
+        requestOptions: { dispatcher: new Agent({ headersTimeout: 5000, bodyTimeout: 5000 }) },
+    },
+    auth: { type: 'token', config: { token: '...' } },
+});
+```
+
+A failed request rejects with `TypeError: fetch failed`, with `cause.code` set to
+`UND_ERR_HEADERS_TIMEOUT` or `UND_ERR_BODY_TIMEOUT`.
+
+Do **not** put `signal: AbortSignal.timeout(ms)` in `requestOptions`. It is created once and
+shared by every request the client makes, so it works for the first call and then aborts all
+later ones with `TimeoutError`. Pass a fresh signal per call, or use the dispatcher above.
+
+##### 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 host that
+can answer for `api.url` can therefore redirect the client and receive its Vault token, so treat
+`api.url` (and the DNS and any load balancer in front of it) as trusted infrastructure.
+
 <a name="VaultClient+fillNodeConfig"></a>
 
 #### vaultClient.fillNodeConfig() ⇒ <code>Promise</code>
 Populates Vault's values to NPM "config" module
 
-Resolves once the npm `config` module has been populated from Vault.
+Resolves once the npm `config` module has been populated from Vault. Note that setup failures are thrown **synchronously**, not returned as a rejected promise: a missing `config` peer dependency and an unreadable `<NODE_CONFIG_DIR>/custom-vault-variables.js` both throw `VaultError` before the promise is created, so use `await` or wrap the call in `try`/`catch` rather than relying on `.catch()` alone.
 
 **Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
 <a name="VaultClient+read"></a>
@@ -358,7 +694,7 @@ The destroyed version data cannot be recovered. KV v2 only — rejects with
 #### vaultClient.readMetadata(path) ⇒ <code>Promise.&lt;Object&gt;</code>
 Reads KV v2 metadata for a secret
 
-Resolves to the metadata document (`current_version`, the `versions` map, timestamps, etc.).
+Resolves to the raw parsed Vault response body; the metadata document (`current_version`, the `versions` map, timestamps, etc.) is under its `data` property, e.g. `(await client.readMetadata('secret/foo')).data.current_version`.
 KV v2 only — rejects with `UnsupportedOperationError` on non-v2 mounts.
 
 **Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
@@ -402,6 +738,12 @@ vaultClient.close(); // process can now exit
 
 **Kind**: instance method of [<code>VaultClient</code>](#VaultClient)  
 
+
+`close()` also settles a renewal that is already in flight: a request that lands after the call is
+discarded rather than arming a fresh timer, so the client stops holding the event loop open. The
+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.
+
 <a name="Lease"></a>
 
 ### Lease
@@ -412,22 +754,31 @@ accessors to extract the secret data:
 * `getValue(key)` ⇒ <code>String</code> — value for a single key. Throws `Requested key does not exist` when the key is absent.
 * `getData()` ⇒ <code>Object</code> — a deep-cloned copy of the whole secret data object.
 * `isRenewable()` ⇒ <code>boolean</code> — whether the underlying lease is renewable.
+* `getMetadata()` ⇒ <code>Object</code> | <code>undefined</code> — KV v2 version metadata
+  (`version`, `created_time`, `deletion_time`, `destroyed`, `custom_metadata`), or `undefined`
+  on KV v1 and non-KV mounts. See [Lease.getMetadata()](#leasegetmetadata).
 
 <a name="VaultClient.boot"></a>
 
-#### VaultClient.boot(name, [options]) ⇒ <code>VaultClient</code>
+#### VaultClient.boot(name, options) ⇒ <code>VaultClient</code>
 Boot an instance of Vault
 
 The instance will be stored in a local hash. Calling Vault.boot multiple
 times with the same name will return the same instance.
 
+`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 passed to it; when those differ from
+the ones it was booted with, the client logs a warning rather than letting the difference pass
+silently. Use [`VaultClient.get(name)`](#VaultClient.get) to fetch an existing instance, or
+[`VaultClient.clear(name)`](#VaultClient.clear) before booting to replace one.
+
 **Kind**: static method of [<code>VaultClient</code>](#VaultClient)  
 **Returns**: <code>VaultClient</code>  
 
 | Param | Type | Description |
 | --- | --- | --- |
 | name | <code>String</code> | Vault instance name |
-| [options] | <code>Object</code> | options for [Vault#constructor](#new_VaultClient_new). |
+| options | <code>Object</code> | options for [Vault#constructor](#new_VaultClient_new). Required on every call, including for a name that was already booted — use [VaultClient.get(name)](#VaultClient.get) to fetch an existing instance. |
 
 <a name="VaultClient.get"></a>
 
@@ -507,7 +858,7 @@ const client = VaultClient.boot('main', {
 
 ### KV v2-specific methods
 
-These methods require a KV v2 mount and throw `UnsupportedOperationError` on v1 / non-KV mounts.
+These methods require a KV v2 mount and throw `UnsupportedOperationError` on v1 / non-KV mounts. They also require the mount to be *resolved* as v2: with neither `api.kv.autoDetect: true` nor an `api.engines` entry covering the mount, every path resolves as v1 passthrough with no detection call, and these methods fail with `UnsupportedOperationError` (`Mount "secret" is not a KV v2 engine.`) even against a genuine KV v2 mount.
 
 ```javascript
 // Soft-delete specific versions
@@ -519,7 +870,8 @@ await client.undeleteVersions('secret/foo', [1]);
 // Permanently destroy versions
 await client.destroyVersions('secret/foo', [1, 2]);
 
-// Read version metadata (current_version, versions map, etc.)
+// Read version metadata. The full Vault envelope is returned, so the metadata
+// fields live under `.data` (meta.data.current_version, meta.data.versions, ...)
 const meta = await client.readMetadata('secret/foo');
 
 // Delete all metadata and version history (permanent)
@@ -591,17 +943,38 @@ await client.request('GET', 'secret/data/foo');
 
 ### Mount detection caching
 
-- Each canonical mount is detected at most once per `VaultClient` instance.
+- Each canonical mount is detected once and then cached for the life of the `VaultClient` instance. The cache is a bounded LRU with a fixed cap of 500 mounts (not configurable through client options); a long-lived client that touches more than 500 distinct mounts evicts the least-recently-used entries, and an evicted mount is detected again on its next use.
 - Concurrent first-touch requests for the same mount share a single in-flight detection promise.
 - The detection endpoint used is `GET sys/internal/ui/mounts/<path>` (readable by any authenticated token).
 - When the token lacks permission on that endpoint, set `api.engines` to skip detection.
 
 ### Error classes
 
-| Class | When thrown |
-|---|---|
-| `UnsupportedOperationError` | A v2-only method (`deleteVersions`, `undeleteVersions`, `destroyVersions`, `readMetadata`, `deleteMetadata`) is called against a non-v2 mount. |
-| `VaultError` | Mount detection fails (e.g. permission denied) and no `api.engines` override was provided. |
+Every error the client raises extends `VaultError`. The package entry point exports the
+`VaultClient` class only, so the classes themselves are imported from `node-vault-client/src/errors`:
+
+```javascript
+const errors = require('node-vault-client/src/errors');
+
+try {
+    await client.readMetadata('secret/app');
+} catch (err) {
+    if (err instanceof errors.UnsupportedOperationError) {
+        // the mount did not resolve as KV v2 - see "Path requirements" above
+        return null;
+    }
+    throw err;
+}
+```
+
+| 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`. |
+| `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 an invalid node-config substitution map. |
+| `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; other backends reach this only with `renewal: false` and a credential they cannot replay. |
+| `UnsupportedOperationError` | `VaultError` | A v2-only method (`deleteVersions`, `undeleteVersions`, `destroyVersions`, `readMetadata`, `deleteMetadata`) was called against a mount that did not resolve as KV v2. |
 
 ## Contributing
 

package/index.d.ts

@@ -0,0 +1,131 @@
+export = VaultClient;
+
+declare class VaultClient {
+    constructor(options: VaultClient.VaultOptions);
+
+    static boot(name: string, options: VaultClient.VaultOptions): VaultClient;
+    static get(name: string): VaultClient;
+    static clear(name?: string): void;
+
+    read(path: string): Promise<VaultClient.Lease>;
+    list(path: string): Promise<VaultClient.Lease>;
+    write(path: string, data: Record<string, any>): Promise<any>;
+    delete(path: string): Promise<any>;
+    update(path: string, data: Record<string, any>): Promise<any>;
+    request(method: string, path: string, data?: Record<string, any>): Promise<any>;
+
+    deleteVersions(path: string, versions: number[]): Promise<any>;
+    undeleteVersions(path: string, versions: number[]): Promise<any>;
+    destroyVersions(path: string, versions: number[]): Promise<any>;
+    readMetadata(path: string): Promise<any>;
+    deleteMetadata(path: string): Promise<any>;
+
+    fillNodeConfig(): Promise<any>;
+    getHeaders(token: VaultClient.AuthToken): Record<string, string>;
+    close(): void;
+}
+
+declare namespace VaultClient {
+    interface Logger {
+        error(...args: any[]): void;
+        warn(...args: any[]): void;
+        info(...args: any[]): void;
+        debug(...args: any[]): void;
+        trace(...args: any[]): void;
+    }
+
+    interface ApiConfig {
+        url: string;
+        apiVersion?: string;
+        namespace?: string;
+        requestOptions?: Record<string, any>;
+        kv?: { autoDetect?: boolean };
+        engines?: Record<string, 1 | 2>;
+    }
+
+    interface AWSCredentials {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    }
+
+    interface TokenAuthConfig {
+        token: string;
+        namespace?: string;
+    }
+
+    interface AppRoleAuthConfig {
+        role_id: string;
+        secret_id?: string;
+        namespace?: string;
+    }
+
+    interface IAMAuthConfig {
+        role: string;
+        credentials?: AWSCredentials;
+        iam_server_id_header_value?: string;
+        region?: string;
+        namespace?: string;
+    }
+
+    interface KubernetesAuthConfig {
+        role: string;
+        tokenPath?: string;
+        namespace?: string;
+    }
+
+    interface JwtAuthConfigCommon {
+        role?: string;
+        namespace?: string;
+    }
+
+    type JwtDistributedClaimConfig =
+        | { distributedClaimAccessToken?: never; distributedClaimAccessTokenProvider?: never }
+        | { distributedClaimAccessToken: string; distributedClaimAccessTokenProvider?: never }
+        | { distributedClaimAccessTokenProvider: () => string | Promise<string>; distributedClaimAccessToken?: never };
+
+    type JwtAuthConfig = JwtAuthConfigCommon &
+        (
+            | { jwt: string; jwtPath?: never; jwtProvider?: never }
+            | { jwtPath: string; jwt?: never; jwtProvider?: never }
+            | { jwtProvider: () => string | Promise<string>; jwt?: never; jwtPath?: never }
+        ) &
+        JwtDistributedClaimConfig;
+
+    interface AuthOptionsCommon {
+        mount?: string;
+        renewal?: boolean;
+        renewalFraction?: number;
+        renewalIncrement?: number;
+    }
+
+    type AuthOptions = AuthOptionsCommon &
+        (
+            | { type: 'token'; config: TokenAuthConfig }
+            | { type: 'appRole'; config: AppRoleAuthConfig }
+            | { type: 'iam'; config: IAMAuthConfig }
+            | { type: 'kubernetes'; config: KubernetesAuthConfig }
+            | { type: 'jwt'; config: JwtAuthConfig }
+        );
+
+    interface VaultOptions {
+        api: ApiConfig;
+        auth: AuthOptions;
+        logger?: Partial<Logger> | false;
+    }
+
+    interface Lease {
+        getValue<T = any>(key: string): T;
+        getData<T = Record<string, any>>(): T;
+        isRenewable(): boolean;
+        getMetadata(): Record<string, any> | undefined;
+    }
+
+    interface AuthToken {
+        getId(): string;
+        getAccessor(): string;
+        isExpired(): boolean;
+        isRenewable(): boolean;
+        getExpiresAt(): number | null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-vault-client",
-  "version": "2.1.2",
+  "version": "2.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"
@@ -9,17 +9,22 @@
     "node": ">=18.0.0"
   },
   "main": "src/VaultClient.js",
+  "types": "index.d.ts",
   "files": [
-    "src"
+    "src",
+    "index.d.ts"
   ],
   "scripts": {
     "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:example": "node examples/jwt-auth/vault-jwt-demo.mjs",
     "coverage": "c8 npm run test:unit",
-    "lint": "eslint src/ test/",
-    "version": "git add -A ."
+    "lint": "eslint src/ test/ examples/",
+    "version": "git add CHANGELOG.md package.json package-lock.json"
   },
   "c8": {
     "include": [
@@ -52,7 +57,7 @@
     "glob": "^13.0.0",
     "diff": "^8.0.3",
     "brace-expansion": "^5.0.9",
-    "js-yaml": "^4.3.0"
+    "js-yaml": "^4.3.2"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.5",
@@ -64,6 +69,7 @@
     "lodash": "^4.18.1",
     "mocha": "^11.7.6",
     "sinon": "^22.1.0",
-    "sinon-chai": "^4.0.1"
+    "sinon-chai": "^4.0.1",
+    "typescript": "^7.0.2"
   }
 }

package/src/VaultClient.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const Lease = require('./Lease');
+const crypto = require('crypto');
 const errors = require('./errors');
 const VaultApiClient = require('./VaultApiClient');
 const VaultAppRoleAuth = require('./auth/VaultAppRoleAuth');
@@ -8,12 +9,46 @@ const VaultTokenAuth = require('./auth/VaultTokenAuth');
 const VaultIAMAuth = require('./auth/VaultIAMAuth');
 const VaultNodeConfig = require('./VaultNodeConfig');
 const VaultKubernetesAuth = require('./auth/VaultKubernetesAuth');
+const VaultJwtAuth = require('./auth/VaultJwtAuth');
 const MountResolver = require('./MountResolver');
 const { rewritePath, normalizeResponse } = require('./kvTransform');
+const { warnIfNode18 } = require('./checkNodeVersion');
+
+warnIfNode18();
 
 const noop = () => {};
 const vaultInstances = {};
 
+/**
+ * Order-insensitive canonical form of the boot options, hashed so that no credential is
+ * retained just to compare two boot() calls. Functions compare by identity, which is what
+ * a caller passing `jwtProvider` expects.
+ */
+function fingerprintOptions(value, seen) {
+    if (typeof value === 'function') {
+        return 'fn';
+    }
+    if (value === null || typeof value !== 'object') {
+        return JSON.stringify(value) || String(value);
+    }
+    seen = seen || new Set();
+    if (seen.has(value)) {
+        return 'circular';
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => fingerprintOptions(item, seen)).join(',')}]`;
+    }
+    const body = Object.keys(value).sort()
+        .map((key) => `${JSON.stringify(key)}:${fingerprintOptions(value[key], seen)}`)
+        .join(',');
+    return `{${body}}`;
+}
+
+function optionsDigest(options) {
+    return crypto.createHash('sha256').update(fingerprintOptions(options)).digest('hex');
+}
+
 class VaultClient {
 
     /**
@@ -33,8 +68,17 @@ class VaultClient {
      *      every request across all auth backends. For backward compatibility `options.auth.config.namespace`
      *      is also honored when this is not set.
      * @param {Object} options.auth
-     * @param {String} options.auth.type
+     * @param {String} options.auth.type - one of: 'appRole' | 'token' | 'iam' | 'kubernetes' | 'jwt'
      * @param {Object} options.auth.config - auth configuration variables
+     * @param {boolean} [options.auth.renewal=true] - Set `false` to never renew the Vault token in
+     *      the background. The token is then used until it expires and the next call
+     *      re-authenticates. Note `token` auth cannot re-authenticate and will raise
+     *      {@link AuthTokenExpiredError} from that point on.
+     * @param {number} [options.auth.renewalFraction=0.5] - How much of the token's remaining
+     *      lifetime to wait before renewing, as a fraction in `(0, 1)`.
+     * @param {number} [options.auth.renewalIncrement] - Seconds of extra TTL to request on each
+     *      renewal, sent as `increment` to `auth/token/renew-self`. Vault caps it at the token's
+     *      max TTL. Omitted by default, which lets Vault apply the token's own period.
      * @param {Object|false} options.logger - Logger that supports "error", "info", "warn", "trace", "debug" methods. Uses `console` by default. Pass `false` to disable logging.
      */
     constructor(options) {
@@ -63,6 +107,12 @@ class VaultClient {
             this.__api
         );
 
+        // Renewal options live on `auth`, not inside `auth.config`: `auth.config` is the
+        // backend's own credential bag and may already carry consumer-specific keys, so
+        // reserving names in it could break an existing caller. Same reasoning that moved
+        // `namespace` to `api.namespace`.
+        this.__auth.configureRenewal(options.auth);
+
         // KV v2 support
         const kvOpts = (options.api && options.api.kv) || {};
         const autoDetect = kvOpts.autoDetect === true;
@@ -89,8 +139,15 @@ class VaultClient {
      * The instance will be stored in a local hash. Calling Vault.boot multiple
      * times with the same name will return the same instance.
      *
+     * `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.
+     *
      * @param {String} name - Vault instance name
-     * @param {Object} [options] - options for {@link VaultClient#constructor}.
+     * @param {Object} options - options for {@link VaultClient#constructor}. Required on
+     *      every call, including for a name that already exists.
      * @return {VaultClient}
      */
     static boot(name, options) {
@@ -101,6 +158,15 @@ class VaultClient {
         let instance = vaultInstances[name];
         if (instance === undefined) {
             vaultInstances[name] = instance = new VaultClient(options);
+            instance.__bootDigest = optionsDigest(options);
+        } else if (instance.__bootDigest !== optionsDigest(options)) {
+            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
+            );
         }
         return instance;
     }
@@ -208,6 +274,13 @@ class VaultClient {
                     authConfig.config,
                     authConfig.mount
                 );
+            case 'jwt':
+                return new VaultJwtAuth(
+                    api,
+                    this.__log,
+                    authConfig.config,
+                    authConfig.mount
+                );
         }
 
         throw new errors.InvalidArgumentsError('Unsupported auth method')

package/src/auth/VaultBaseAuth.js

@@ -6,6 +6,9 @@
 // only if a maintained alternative or a Node.js core fix appears.
 const lt = require('long-timeout');
 const AuthToken = require('./AuthToken');
+
+/** Renew at the halfway point of the token's remaining lifetime. */
+const DEFAULT_RENEWAL_FRACTION = 0.5;
 const errors = require('../errors');
 
 /**
@@ -37,6 +40,9 @@ class VaultBaseAuth {
         /** @protected */
         this._log = logger;
         this._mount = mount;
+        this.__renewalEnabled = true;
+        this.__renewalFraction = DEFAULT_RENEWAL_FRACTION;
+        this.__renewalIncrement = undefined;
 
         /**
          * The currently held token, or `null` when none has been obtained yet.
@@ -50,6 +56,90 @@ class VaultBaseAuth {
          */
         this.__pendingLogin = null;
         this.__refreshTimeout = null;
+        this.__renewalEpoch = 0;
+    }
+
+    /**
+     * Apply the renewal options from `auth`. Separate from the constructor so that the
+     * subclass signatures -- and this one -- stay exactly as they were: anything already
+     * subclassing VaultBaseAuth keeps working untouched.
+     *
+     * @param {Object} [authConfig] - the `auth` block from VaultClient's options
+     * @param {boolean} [authConfig.renewal=true]
+     * @param {number} [authConfig.renewalFraction=0.5]
+     * @param {number} [authConfig.renewalIncrement]
+     * @returns {void}
+     */
+    configureRenewal(authConfig) {
+        this.__renewalEnabled = VaultBaseAuth.__validateRenewal(authConfig);
+        this.__renewalFraction = VaultBaseAuth.__validateFraction(authConfig);
+        this.__renewalIncrement = VaultBaseAuth.__validateIncrement(authConfig);
+    }
+
+    /**
+     * Strict on purpose: node-config's `custom-environment-variables` yields strings, so a
+     * loose check would read `VAULT_RENEWAL=false` as `'false'` and leave renewal on -- the
+     * exact hang the flag exists to prevent, silently.
+     *
+     * @param {Object} [authConfig]
+     * @returns {boolean}
+     * @private
+     */
+    static __validateRenewal(config) {
+        if (!config || config.renewal === undefined) {
+            return true;
+        }
+
+        if (typeof config.renewal !== 'boolean') {
+            throw new errors.InvalidArgumentsError(
+                `"renewal" should be a boolean, got ${String(config.renewal)}`
+            );
+        }
+
+        return config.renewal;
+    }
+
+    /**
+     * @param {Object} [authConfig]
+     * @returns {number}
+     * @private
+     */
+    static __validateFraction(config) {
+        if (!config || config.renewalFraction === undefined) {
+            return DEFAULT_RENEWAL_FRACTION;
+        }
+
+        const fraction = config.renewalFraction;
+        // Exclusive upper bound: at exactly 1 the timer fires at the same instant
+        // getAuthToken() starts treating the token as expired, racing the client's own
+        // re-authentication and leaving no headroom for the renewal request itself.
+        if (typeof fraction !== 'number' || !Number.isFinite(fraction) || fraction <= 0 || fraction >= 1) {
+            throw new errors.InvalidArgumentsError(
+                `"renewalFraction" should be a number in (0, 1), got ${String(fraction)}`
+            );
+        }
+
+        return fraction;
+    }
+
+    /**
+     * @param {Object} [authConfig]
+     * @returns {number|undefined}
+     * @private
+     */
+    static __validateIncrement(config) {
+        if (!config || config.renewalIncrement === undefined) {
+            return undefined;
+        }
+
+        const increment = config.renewalIncrement;
+        if (!Number.isInteger(increment) || increment <= 0) {
+            throw new errors.InvalidArgumentsError(
+                `"renewalIncrement" should be a positive integer number of seconds, got ${String(increment)}`
+            );
+        }
+
+        return increment;
     }
 
     /**
@@ -84,12 +174,24 @@ class VaultBaseAuth {
         const pendingLogin = this._authenticate().then(authToken => {
             this.__pendingLogin = null;
             this.__authToken = authToken;
+            this.__renewalEpoch++;
 
             if (authToken.isRenewable()) {
-                this._log.debug(
-                    'setting refresh timer for token (accessor=%s)',
-                    authToken.getAccessor()
-                );
+                // Gate the log on the flag too: the guard lives inside
+                // __setupTokenRefreshTimer, so without this the client claims it armed a
+                // timer while arming nothing -- the one diagnostic an operator reads when a
+                // `renewal: false` process still hangs.
+                if (this.__renewalEnabled) {
+                    this._log.debug(
+                        'setting refresh timer for token (accessor=%s)',
+                        authToken.getAccessor()
+                    );
+                } else {
+                    this._log.debug(
+                        'renewal disabled by config; not arming a refresh timer (accessor=%s)',
+                        authToken.getAccessor()
+                    );
+                }
                 this.__setupTokenRefreshTimer(authToken);
             }
 
@@ -116,6 +218,7 @@ class VaultBaseAuth {
      * @returns {void}
      */
     cancelTokenRefresh() {
+        this.__renewalEpoch++;
         if (this.__refreshTimeout !== null) {
             lt.clearTimeout(this.__refreshTimeout);
             this.__refreshTimeout = null;
@@ -151,17 +254,35 @@ class VaultBaseAuth {
             this.__refreshTimeout = null;
         }
 
-        if (!authToken.isRenewable() || authToken.isExpired()) {
+        if (!this.__renewalEnabled || !authToken.isRenewable() || authToken.isExpired()) {
             return;
         }
 
-        const timer = Math.max((authToken.getExpiresAt() - Math.floor(Date.now() / 1000)) / 2, 1) * 1000;
+        const remaining = authToken.getExpiresAt() - Math.floor(Date.now() / 1000);
+        const timer = Math.max(remaining * this.__renewalFraction, 1) * 1000;
+
+        // 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
+        // permanently un-renewed. Anything that supersedes this timer bumps the epoch.
+        const epoch = ++this.__renewalEpoch;
+        const superseded = () => this.__renewalEpoch !== epoch;
 
         this.__refreshTimeout = lt.setTimeout(() => {
-            this.__renewToken(authToken).then(authToken => {
-                this.__authToken = authToken;
-                this.__setupTokenRefreshTimer(authToken);
+            if (superseded()) {
+                return;
+            }
+
+            this.__renewToken(authToken).then(renewedToken => {
+                if (superseded()) {
+                    return;
+                }
+                this.__authToken = renewedToken;
+                this.__setupTokenRefreshTimer(renewedToken);
             }).catch(err => {
+                if (superseded()) {
+                    return;
+                }
                 this.__setupTokenRefreshTimer(authToken);
 
                 this._log.error(`Cannot refresh auth token with "${authToken.getAccessor()}" accessor. Error: ${err.message}`);
@@ -183,7 +304,10 @@ class VaultBaseAuth {
     __renewToken(authToken) {
         this._log.debug('renewing vault token');
 
-        return this.__apiClient.makeRequest('POST', '/auth/token/renew-self', null, {'X-Vault-Token': authToken.getId()})
+        // null, not {}, when unset: that is the body the client has always sent.
+        const data = this.__renewalIncrement === undefined ? null : {increment: this.__renewalIncrement};
+
+        return this.__apiClient.makeRequest('POST', '/auth/token/renew-self', data, {'X-Vault-Token': authToken.getId()})
             .then(() => {
                 this._log.info('successfully renewed token');
                 return this._getTokenEntity(authToken.getId());

package/src/auth/VaultJwtAuth.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const fs = require('fs');
+const VaultBaseAuth = require('./VaultBaseAuth');
+const errors = require('../errors');
+
+const JWT_SOURCE_KEYS = ['jwt', 'jwtPath', 'jwtProvider'];
+
+class VaultJwtAuth extends VaultBaseAuth {
+    /**
+     * @param {VaultApiClient} apiClient - see {@link VaultBaseAuth#constructor}
+     * @param {Object} logger
+     * @param {Object} config
+     * @param {String} [config.role] - Role configured in Vault's JWT auth backend. Optional;
+     *   when omitted, Vault falls back to the mount's configured `default_role`.
+     * @param {String} [config.jwt] - A literal JWT to present at login. Exactly one of
+     *   `jwt` / `jwtPath` / `jwtProvider` must be provided.
+     * @param {String} [config.jwtPath] - Path to a file containing the JWT. Re-read on every
+     *   login (like {@link VaultKubernetesAuth}'s `tokenPath`), so a rotated token is picked up.
+     * @param {Function} [config.jwtProvider] - (optionally async) function invoked at login time,
+     *   returning `string | Promise<string>`. Called fresh on every login (never at construction
+     *   or cached across logins) so it can mint a short-lived token -- the shape GitHub Actions'
+     *   `core.getIDToken()`, cloud metadata endpoints and SPIFFE workloads need.
+     * @param {String} [config.distributedClaimAccessToken] - A literal OAuth access token forwarded
+     *   to Vault as `distributed_claim_access_token`. Azure/Entra roles with `fetch_groups` enabled
+     *   need it so Vault can resolve the distributed group-membership claim against the Microsoft
+     *   Graph API. Optional, and mutually exclusive with `distributedClaimAccessTokenProvider`.
+     * @param {Function} [config.distributedClaimAccessTokenProvider] - (optionally async) function
+     *   invoked at login time, returning `string | Promise<string>`. Called fresh on every login
+     *   (never at construction or cached across logins) because Graph access tokens are short-lived
+     *   and are usually acquired next to the JWT itself. Mutually exclusive with
+     *   `distributedClaimAccessToken`.
+     * @param {String} [config.namespace] - Optional. Vault namespace. Applied as the X-Vault-Namespace
+     *   header to every request by {@link VaultApiClient}; see {@link VaultClient#constructor}.
+     * @param {String} mount - Vault's mount point ("jwt" by default)
+     */
+    constructor(apiClient, logger, config, mount) {
+        super(apiClient, logger, mount || 'jwt');
+
+        const providedSources = JWT_SOURCE_KEYS.filter((key) => config && config[key] !== undefined);
+        if (providedSources.length !== 1) {
+            throw new errors.InvalidArgumentsError(
+                'Exactly one of "jwt", "jwtPath" or "jwtProvider" should be provided for VaultJwtAuth'
+            );
+        }
+        if (config.jwtProvider !== undefined && typeof config.jwtProvider !== 'function') {
+            throw new errors.InvalidArgumentsError('"jwtProvider" should be a function for VaultJwtAuth');
+        }
+        if (config.distributedClaimAccessToken !== undefined
+            && config.distributedClaimAccessTokenProvider !== undefined) {
+            throw new errors.InvalidArgumentsError(
+                'Only one of "distributedClaimAccessToken" or "distributedClaimAccessTokenProvider"'
+                + ' should be provided for VaultJwtAuth'
+            );
+        }
+        if (config.distributedClaimAccessTokenProvider !== undefined
+            && typeof config.distributedClaimAccessTokenProvider !== 'function') {
+            throw new errors.InvalidArgumentsError(
+                '"distributedClaimAccessTokenProvider" should be a function for VaultJwtAuth'
+            );
+        }
+
+        this.__role = config.role;
+        this.__jwt = config.jwt;
+        this.__jwtPath = config.jwtPath;
+        this.__jwtProvider = config.jwtProvider;
+        this.__distributedClaimAccessToken = config.distributedClaimAccessToken;
+        this.__distributedClaimAccessTokenProvider = config.distributedClaimAccessTokenProvider;
+    }
+
+    _authenticate() {
+        return Promise.resolve()
+            .then(() => this.__acquireJwt())
+            .then(({ jwt, source }) => Promise.resolve()
+                .then(() => this.__acquireDistributedClaimAccessToken())
+                .then((distributedClaim) => {
+                    this._log.info(
+                        'making authentication request: Vault role: "%s"; JWT source: %s (%d bytes)%s',
+                        this.__role !== undefined ? this.__role : '(default_role)', source, jwt.length,
+                        distributedClaim === undefined
+                            ? ''
+                            : `; distributed claim access token: ${distributedClaim.source}`
+                    );
+
+                    const body = { jwt };
+                    if (this.__role !== undefined) {
+                        body.role = this.__role;
+                    }
+                    if (distributedClaim !== undefined) {
+                        body.distributed_claim_access_token = distributedClaim.accessToken;
+                    }
+
+                    return this.__apiClient.makeRequest('POST', `/auth/${this._mount}/login`, body)
+                        .then((res) => {
+                            this._log.debug('received Vault client token from JWT login');
+
+                            return this._getTokenEntity(res.auth.client_token);
+                        });
+                }));
+    }
+
+    /**
+     * @returns {{jwt: String, source: String}|Promise<{jwt: String, source: String}>}
+     * @private
+     */
+    __acquireJwt() {
+        if (this.__jwt !== undefined) {
+            return { jwt: this.__jwt, source: 'literal' };
+        }
+        if (this.__jwtPath !== undefined) {
+            return { jwt: fs.readFileSync(this.__jwtPath).toString(), source: 'file' };
+        }
+
+        // Wrapping in Promise.resolve().then() normalizes both a sync provider (plain return)
+        // and a synchronous throw into the same rejection path as an async one.
+        return Promise.resolve().then(() => this.__jwtProvider()).then((jwt) => {
+            if (typeof jwt !== 'string' || jwt.length === 0) {
+                throw new errors.InvalidArgumentsError(
+                    '"jwtProvider" must resolve to a non-empty JWT string'
+                );
+            }
+            return { jwt, source: 'provider' };
+        });
+    }
+
+    /**
+     * Resolves to `undefined` when neither option is configured, so that the login body stays
+     * byte-identical to what it was before this option existed.
+     *
+     * @returns {undefined|{accessToken: String, source: String}|Promise<{accessToken: String, source: String}>}
+     * @private
+     */
+    __acquireDistributedClaimAccessToken() {
+        if (this.__distributedClaimAccessToken !== undefined) {
+            return { accessToken: this.__distributedClaimAccessToken, source: 'literal' };
+        }
+        if (this.__distributedClaimAccessTokenProvider === undefined) {
+            return undefined;
+        }
+
+        // Wrapping in Promise.resolve().then() normalizes both a sync provider (plain return)
+        // and a synchronous throw into the same rejection path as an async one.
+        return Promise.resolve().then(() => this.__distributedClaimAccessTokenProvider()).then((accessToken) => {
+            if (typeof accessToken !== 'string' || accessToken.length === 0) {
+                throw new errors.InvalidArgumentsError(
+                    '"distributedClaimAccessTokenProvider" must resolve to a non-empty access token string'
+                );
+            }
+            return { accessToken, source: 'provider' };
+        });
+    }
+}
+
+module.exports = VaultJwtAuth;

package/src/checkNodeVersion.js

@@ -0,0 +1,27 @@
+'use strict';
+
+const NODE_18_DEPRECATION_MESSAGE =
+    'node-vault-client: this is the last release of this package to support Node.js 18. ' +
+    'Node 18 reached end-of-life on 2025-04-30 and no longer receives security patches from ' +
+    'the Node.js project. The next major release of node-vault-client will require ' +
+    'Node.js >= 20.19.0 — see CHANGELOG.md for details.';
+const NODE_18_DEPRECATION_CODE = 'NodeVaultClientNode18Deprecation';
+
+/**
+ * Emits a one-time process warning when running on Node.js 18. Called once, at module load,
+ * from VaultClient.js — require()'s own module cache is what keeps it to once per process,
+ * not any dedup logic here.
+ *
+ * Takes a `process`-like object (defaulting to the real `process`) purely so tests can assert
+ * the behaviour on a stubbed Node version instead of on whatever Node this suite happens to run
+ * under.
+ */
+function warnIfNode18(proc) {
+    proc = proc || process;
+    const nodeVersion = proc.versions && proc.versions.node;
+    if (typeof nodeVersion === 'string' && /^18\./.test(nodeVersion)) {
+        proc.emitWarning(NODE_18_DEPRECATION_MESSAGE, { code: NODE_18_DEPRECATION_CODE });
+    }
+}
+
+module.exports = { warnIfNode18, NODE_18_DEPRECATION_MESSAGE, NODE_18_DEPRECATION_CODE };

package/src/errors.d.ts

@@ -0,0 +1,18 @@
+export declare class VaultError extends Error {
+    constructor(message: string, options?: { cause?: unknown });
+    name: string;
+}
+
+export declare class InvalidArgumentsError extends VaultError {}
+
+export declare class InvalidAWSCredentialsError extends InvalidArgumentsError {}
+
+export declare class AuthTokenExpiredError extends VaultError {}
+
+export declare class UnsupportedOperationError extends VaultError {}
+
+export declare class VaultHttpError extends VaultError {
+    constructor(statusCode: number, text: string, body?: unknown);
+    statusCode: number;
+    error: unknown;
+}