get-jwks

library11.0.3jsnpmunverified

Fetch utility for JSON Web Key Sets (JWKS) with caching, issuer validation, and provider discovery. Current stable version: 11.0.3, requires Node.js >=20, ships TypeScript types. Uses lru-cache for key caching and supports OpenID Connect Discovery. Differentiators: built-in stale cache fallback on errors, configurable issuer whitelist/check, and fetch options customization. ESM-only since v10. Common alternatives: jwks-rsa (more features), this package is leaner for serverless.

security devops

npm install get-jwks

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GET-JWKS

get-jwks

securityjavascriptv11.0.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

buildGetJwks

✓ import buildGetJwks from 'get-jwks'

✗ const buildGetJwks = require('get-jwks')

Package is ESM-only since v10, use default import. CJS require() works in Node 20+ due to interop but is not recommended.

getJwk

✓ const getJwks = buildGetJwks(); const jwk = await getJwks.getJwk({ domain: '...', kid: '...' })

✗ buildGetJwks.getJwk()

getJwk is an instance method on the object returned by buildGetJwks().

getPublicKey

✓ const getJwks = buildGetJwks(); const key = await getJwks.getPublicKey({ domain: '...', kid: '...' })

✗ const key = await getJwks.getJwk({...})

getPublicKey returns PEM string, getJwk returns JWK object. Use getPublicKey for verification with jsonwebtoken.

options (type)

✓ import type { Options } from 'get-jwks'

TypeScript users should import the Options type for type-safe configuration.

Shows how to fetch a JWKS public key and verify a JWT using jsonwebtoken with TypeScript.

import buildGetJwks from 'get-jwks'; import jwt from 'jsonwebtoken'; const getJwks = buildGetJwks({ issuersWhitelist: ['https://example.com'], providerDiscovery: false, timeout: 5000 }); async function verifyToken(token: string): Promise<object> { const decoded = jwt.decode(token, { complete: true }); if (!decoded || typeof decoded.payload === 'string') throw new Error('Invalid token'); const header = decoded.header as { alg?: string; kid?: string }; const payload = decoded.payload as { iss?: string }; if (!payload.iss) throw new Error('Missing issuer'); const publicKey = await getJwks.getPublicKey({ domain: payload.iss, alg: header.alg, kid: header.kid }); return jwt.verify(token, publicKey, { algorithms: [header.alg!] }); } // Usage const token = 'eyJ...'; // your JWT const payload = await verifyToken(token); console.log(payload);

Debug

Known issues

breakingModule is ESM-only and requires Node.js >=20. CJS require() may fail or produce unexpected results in older Node runtimes.

fix

Use Node >=20 with ESM imports (import buildGetJwks from 'get-jwks'). If stuck on CJS, use dynamic import or stay on v9.x.

affects: >=10

deprecatedThe 'allowedDomains' option has been deprecated and replaced by 'issuersWhitelist'.

fix

Replace allowedDomains with issuersWhitelist in the options object.

affects: >=6

breakingThe default export changed from a factory to the buildGetJwks function. Previously require('get-jwks') returned a class, now it returns a factory function.

fix

Use buildGetJwks() to create an instance. Old code like const getJwks = require('get-jwks')() still works due to callable default, but type signatures differ.

affects: >=10

gotchaCalling getJwk or getPublicKey with undefined domain will throw a TypeError: Cannot read properties of undefined.

fix

Always provide a domain string. Validate the domain before calling these methods.

affects: all

gotchaThe stale cache fallback may return an outdated key if the JWKS rotates and the provider returns an error. The key is cached for ttl milliseconds, then stale for an additional ttl.

fix

Set appropriate ttl values. Clear cache manually if rotation is detected: getJwks.cache.clear() (if cache is exposed).

affects: all

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'getJwk')

Forgetting to call buildGetJwks() - using it directly without invoking the factory.

fix

const getJwks = buildGetJwks(); then getJwks.getJwk()

Error: Cannot find module 'get-jwks'

Running on Node <20 where the package's ESM-only distribution cannot be required.

fix

Upgrade Node to >=20 or use import() syntax: const getJwks = await import('get-jwks')

Error: issuer not allowed

The issuer in the token is not in the issuersWhitelist or failed the checkIssuer function.

fix

Add the issuer URL to issuersWhitelist: buildGetJwks({ issuersWhitelist: ['https://yourdomain.com'] })

Error: could not retrieve JWKS: fetch failed

The domain URL is invalid, JWKS endpoint unreachable, or timeout exceeded.

fix

Ensure the domain is correct and reachable. Increase timeout option. If using providerDiscovery, verify the OpenID configuration endpoint exists.

Error: Type 'typeof import("...")' has no call signatures

TypeScript types mismatch when using require() with get-jwks v10+.

fix

Switch to import buildGetJwks from 'get-jwks' and ensure tsconfig has "moduleResolution": "nodenext".

Upgrade

Version history

11.0.3latest on npm

Audit

Dependencies

lru-cacherequiredInternal caching for JWKS entries, managed via max/ttl options

Agent activity

17 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/nearform/get-jwks ↗

packageget-jwks ↗

homepagehttps://github.com/nearform/get-jwks#readme ↗