Repository navigation
3.2.0
Upgrading from 3.1.x needs no code change for most setups. What behaves differently is covered
below:
- Redirects are followed only within the origin of
api.url(#232). Anhttp://api.urlthat
a load balancer redirects tohttps://, or a Vault HA standby that redirects to an active node
on another origin, now fails. Use the final URL, or setapi.requestOptions.redirect: 'follow'
for the 3.1.x behaviour. - A 403 on a secret request is checked with
auth/token/lookup-self, and a token Vault no
longer accepts is replaced by one new login (#235). A policy denial is returned as before. - New
warnlines: a plainhttp://api.urloff this machine, and an IAM login without
iam_server_id_header_value(part of #202).VaultClient.clear()with a name that is not a
string emits aDeprecationWarning(#239). None of them changes what the client does.
Changes in this release:
-
CI / release tooling (#229). The publish job holds the npm trusted-publishing credential
(id-token: write). It no longer fetches and runs tooling from outside the lockfile, and what
it must fetch is kept away from that credential.- The job no longer runs
npm install -g npm@latest(npmlatesthad moved to 12.x). It uses
the npm bundled with Node 24 and fails if that is older than 11.5.1, which trusted publishing
needs. npm ci --ignore-scriptsin the publish job. No locked package has an install script today;
this keeps a future one from running there.test/verify-package.mjsstill installs the packed tarball's runtime dependencies from the
registry, as a consumer would, but with--ignore-scriptsand without the OIDC request,
Actions runtime and npm/GitHub token variables, both for the install and for the checks that
load the package.configis locked as a devDependency (^4.4.2, inside the unchanged>=1 <5peer range)
instead ofnpm install configin three CI jobs.test/workflows.test.mjsfails if a workflowrun:command fetches packages at run time
(npm install/add/update/exec,npx,yarn add,pnpm,@latest), if a publish
npm ciloses--ignore-scripts, if the npm check goes, or if verify-package stops
scrubbing the environment.
Library code and runtime dependencies are unchanged; the packed
package.jsonnow also lists
configunderdevDependencies, which consumers do not install. - The job no longer runs
-
A warning for an IAM login without
iam_server_id_header_value(part of #202). The signed
STSGetCallerIdentityrequest then names no Vault server, so it could be replayed to another
Vault server that trusts the same AWS principal. With the value missing, empty or only
whitespace, theiambackend now logs onewarnline on its first login, once per Vault server,
namespace and mount for each logger (clients on the default logger share one, so once per
process), and logs in as before, sending the same request.logger: falsesilences it without
using it up for other clients. A client that never logs in, or whose config is rejected, logs
nothing. README: "iam_server_id_header_value". -
Tests: the e2e suites exit without
--exit(#220). Plainmochaone2e.test.mjsor
e2e.kv2.test.mjshung after the summary. Two clients holding renewable tokens were never
closed, so their renewal timers kept the event loop alive: the AppRole "with secret ID" test,
and the KV path-validation suite shared by both files (a one-hour service token). The renewal
tests named in the issue already closed theirs. Both now close their clients, and the
test:e2e*scripts loadtest/e2e/renewal-timer-guard.mjs. If a renewal timer is still armed
after the last test, it fails the run, naming the test or hook in which that client was first
used, and cancels the timer so the run exits even without--exit.--exitstays in the
scripts. Test-only; no library change. -
A warning for a plain
http://api.urloff this machine (part of #202). Whenapi.urlis
http://and its host is not this machine (localhost,127.0.0.0/8also as
::ffff:127.x.y.z,::1,0.0.0.0,::), the client now logs onewarnline on its first
request, because the token and secrets would cross the network unencrypted. It names only the
host and port, is logged once per host and port for each logger (clients on the default logger
share one, so once per process), and changes nothing else: the client connects and works as
before, and a logger that throws does not fail the request (the client tries again on its next
one). With the default logger it goes toconsole.warn;logger: falsesilences it without
using it up for other clients. README: "Plainhttp://api.url". -
Security: redirects are followed only within the origin of
api.url(#232). Requests
usedfetch()'sredirect: 'follow', which sends every header butAuthorization,Cookie
andProxy-Authorizationto whatever origin aLocationnames.X-Vault-Tokenwent with it, a
307 or 308 on a login replayed the credentials in its body, and the other origin's answer was
returned as Vault data. Requests are now sent withredirect: 'manual', and the client follows
a redirect itself only to the same origin (scheme, host and port), asfetch()would: up to 20
hops, method and body kept on a 307 or 308, aGETwithout a body on a 303 and on a 301 or 302
after aPOST. A redirect to another origin rejects with aVaultErrorbefore anything is
sent there. That includeshttps:tohttp:, andhttp:tohttps:on the same host.- Compatibility. Same-origin redirects, such as Vault's own for a
//in a path, behave as
before. A test sends each redirect status with GET, POST, PUT, PATCH and DELETE both ways and
compares the method, path, body and headers the server receives. Wherefetch()gave up
(more than 20 hops, aLocationthat does not parse, is not http(s) or carries
credentials), the request still rejects withTypeError: fetch failed. Changed:- An
http://api.urlthat a load balancer redirects tohttps://now fails. Use the
https://URL. - A Vault HA standby answers with a 307 to the active node's
api_addrwhen request
forwarding fails. If that address is another origin, the request now fails instead of
following it. - A
redirectinapi.requestOptionsis passed tofetch()as it is;'follow'restores
the old behaviour.redirect: null, whichfetch()rejected on every request, now reads
as not set. fetch()now receivesredirect: 'manual'instead of'follow', withapi.timeout: 0
too. Code that stubsfetch()and checks its options will see this.
- An
- README: "Redirects and the Vault token" describes the policy and the opt-out.
- Compatibility. Same-origin redirects, such as Vault's own for a
-
Fixed:
close()during a login no longer leaves a renewal timer behind (#251). A login that
was still in flight whenclose()ran, such as the firstreadof a client closed before it
settled, armed a refresh timer when it finished, so the process still never exited. Such a login
now resolves and caches its token as before, but arms no timer; adebugline says so. Calls
that join that login afterclose()share its token and get no timer either. A login that starts
afterclose()arms one as before. Dropping a token Vault no longer accepts (#235) does not count
as aclose(): the token from the next login is renewed. The warnings a login logs when it
cannot renew its token are unchanged, and a subclass that overridescancelTokenRefresh(), with
or withoutsuper, keeps both behaviours. -
Fixed: a token lookup without a usable
ttlno longer yields aNaNexpiry (#236). Without
expire_time, the expiry iscreation_time(orlast_renewal_time) plusttl. A
lookup-selfanswer where either was missing or not a number made thatNaN, so
getExpiresAt()returnedNaNand the token counted as renewable. Such a token now has a
nullexpiry, as one withttl: 0and noexpire_timealready had, and is not renewable.- Compatibility. The token is still used until it is replaced: a
NaNdeadline never passed,
and anullone means none. No timer is armed for it, as before. The log output is the same:
the renewal timer still logstoken renewal stopped (accessor=…): token has no usable expiry; …once, after a login or a renewal, when Vault marked the token renewable. A numeric-string
ttlorcreation_timeis read as before. One more case changes: a numeric string too long
to fit in a number used to give a deadline in the past, so every call logged in again. Real
Vault always sends a numericttl, so this only affects proxies, mocks and test doubles.
- Compatibility. The token is still used until it is replaced: a
-
Fixed: a token revoked on the Vault side is replaced on the next request (#235). The client
logged in again only once its own clock said the token had expired. After a server-side
revocation, every request failed withVaultHttpError403 until then, even when the auth backend
could log in again at once. Now a 403 on a secret request (the KV methods,request(), and the
autoDetectmount detection) is checked withauth/token/lookup-self. If Vault no longer accepts
the token, the client drops it with its renewal timer, logs in again and sends the request once
more.- Compatibility. A policy denial is returned as before and costs no login, so an AppRole
secret_idwith limited uses is not spent on it. It does cost one extralookup-selfrequest
(withautoDetect, also for a mount the token may not see), which counts against a token with
limited uses. Each request is sent again at most once, and one login serves every request
rejected with the same token. When that attempt fails, the call rejects with its error (a
failed login, a 404, a timeout) rather than the dead token's 403. A 403 on the login itself
and any 403 undertokenauth are returned as before, without a lookup. Other statuses are
untouched. - Revoking a client's token no longer locks it out: it logs straight back in. To cut a client
off, also revoke or rotate its login credential. - README: "Tokens revoked on the Vault side".
- Compatibility. A policy denial is returned as before and costs no login, so an AppRole
-
Fixed:
VaultClient.get()andboot()with a name such as"toString"(#238). The named
instances lived in a plain object, so a name matching anObject.prototypemember found that
member.get("toString")returnedObject.prototype.toStringinstead of throwing
InvalidArgumentsError, andboot("constructor", options)treatedObjectas an existing
instance and threw aTypeError. The registry is now aMap, so every name,__proto__
included, behaves like any other.- Compatibility. Names are keyed exactly as object properties were: a number is the same
name as its string (boot(1)thenget('1')returns that instance), and a symbol, or an
object that converts to one, stays a symbol.clear()with no name still leaves
symbol-named instances registered, as the oldfor...inloop did.clear('toString')and
the like, which threw aTypeError, now do nothing when no such instance was booted.
- Compatibility. Names are keyed exactly as object properties were: a number is the same
-
A warning when
VaultClient.clear()gets a name that is not a string (#239). Only a
string clears one named instance; anything else, such asclear(42),clear(null)orclear
used as a callback that receives an exit code or a resolved value, closes and removes every
instance except symbol-named ones. That was silent and rarely meant. The behaviour is unchanged,
but the first such call in a process now emits aDeprecationWarning(code
NVC_DEP_CLEAR_NON_STRING) that names the argument's type, never its value. Callclear()with
no argument to clear every instance. Node delivers warnings on the next tick, so inside a
process.on('exit')listener it is not shown;--no-deprecationsilences it. -
Fixed:
Lease.getValue()returned inherited members as secret values (#240). It threw
only whendata[key]wasundefined, sogetValue('constructor')returnedObjectand
getValue('__proto__')returnedObject.prototype. It now returns only the response data's
own fields and throwsRequested key does not existfor anything else.- Compatibility. Own fields are returned as before,
null,false,0and''included,
and so is a field Vault sent under a name such asconstructor. Numeric keys and array
indexes work as before. When a response'sdatais JSONnull, a string or a number, the
call now throwsRequested key does not exist, wherenullgave aTypeErrorand a string
gave one of its characters or its length.
- Compatibility. Own fields are returned as before,
-
Fixed: a missing Kubernetes service-account token file threw out of
read()(#241).
kubernetesauth read the token file before its promise chain, so a missing or unreadable
file maderead(),write()and every other operation throw synchronously instead of
returning a rejected promise. A caller that only chained.catch()got an uncaught
exception. The file is now read inside the chain, asjwtauth already did withjwtPath.
The login also turns a synchronous throw from any auth backend into a rejection.- Compatibility. The operation now rejects with the same
fserror (for example
code: 'ENOENT', with the same message) instead of throwing it, so handle it withawaitor
.catch(): atry/catcharound a call that is not awaited no longer catches it. As with
any other failed operation, it is now logged aterror(read secret failed: ENOENT: …).
Vault is still not contacted. Calls made while that login is still pending share its error;
the next call after it tries the file again, as before.
- Compatibility. The operation now rejects with the same
-
Fixed: each caller gets its own mount-detection error (part of #202). With
api.kv.autoDetect, requests whose paths share a first segment wait for one in-flight
detection. When it failed, every one of them got the sameVaultError, whose message named
the first caller's path. Each caller now gets its ownVaultError, naming its own path. The
underlying error stays oncause, shared by all.- Compatibility. The failure is still shared: one detection request, whatever it answered
(a 403, a rate limit, a failed login), so the request count is unchanged. The message
format, the first caller's message and the error class (VaultError, notVaultHttpError)
are unchanged. The status is still only onerr.cause.statusCode. Copying it onto the error
would let a "403 means use a default" handler swallow a mistyped mount, because Vault answers
403 for a mount that does not exist.
- Compatibility. The failure is still shared: one detection request, whatever it answered