node-vault-client 2.2.0 → 2.3.0

package/README.md

@@ -18,6 +18,12 @@ 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:
@@ -36,7 +42,8 @@ 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.
+`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`
@@ -167,8 +174,9 @@ const vaultClient = VaultClient.boot('main', {
         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)
+            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`
         },
     },
 });
@@ -191,6 +199,96 @@ Exactly one of three mutually exclusive `config` keys supplies the JWT:
   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
@@ -212,6 +310,18 @@ const vaultClient = VaultClient.boot('ci', {
 });
 ```
 
+`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.
 

package/index.d.ts

@@ -79,12 +79,18 @@ declare namespace VaultClient {
         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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-vault-client",
-  "version": "2.2.0",
+  "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"
@@ -57,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",
@@ -70,6 +70,6 @@
     "mocha": "^11.7.6",
     "sinon": "^22.1.0",
     "sinon-chai": "^4.0.1",
-    "typescript": "^5.9.3"
+    "typescript": "^7.0.2"
   }
 }

package/src/VaultClient.js

@@ -12,6 +12,9 @@ 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 = {};

package/src/auth/VaultJwtAuth.js

@@ -21,6 +21,15 @@ class VaultJwtAuth extends VaultBaseAuth {
      *   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)
@@ -37,34 +46,57 @@ class VaultJwtAuth extends VaultBaseAuth {
         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 }) => {
-                this._log.info(
-                    'making authentication request: Vault role: "%s"; JWT source: %s (%d bytes)',
-                    this.__role !== undefined ? this.__role : '(default_role)', source, jwt.length
-                );
+            .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;
-                }
+                    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.__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);
-                    });
-            });
+                            return this._getTokenEntity(res.auth.client_token);
+                        });
+                }));
     }
 
     /**
@@ -90,6 +122,33 @@ class VaultJwtAuth extends VaultBaseAuth {
             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 };