feat: add cacheMaxAgeFallback option for graceful JWKS degradation during outages

index.d.ts

@@ -23,6 +23,7 @@ declare namespace JwksRsa {
     cache?: boolean;
     cacheMaxEntries?: number;
     cacheMaxAge?: number;
+    cacheMaxAgeFallback?: number;
     jwksRequestsPerMinute?: number;
     proxy?: string;
     requestHeaders?: Headers;

package.json

@@ -16,6 +16,7 @@
     "debug": "^4.3.4",
     "jose": "^6.1.3",
     "limiter": "^1.1.5",
+    "lru-cache": "^11.0.0",
     "lru-memoizer": "^3.0.0"
   },
   "devDependencies": {

src/wrappers/cache.js

@@ -1,12 +1,34 @@
 const logger = require('debug')('jwks');
 const memoizer = require('lru-memoizer');
+const { LRUCache } = require('lru-cache');
 const { promisify, callbackify } = require('util');
 
-function cacheWrapper(client, { cacheMaxEntries = 5, cacheMaxAge = 600000 }) {
-  logger(`Configured caching of signing keys. Max: ${cacheMaxEntries} / Age: ${cacheMaxAge}`);
+function cacheWrapper(client, { cacheMaxEntries = 5, cacheMaxAge = 600000, cacheMaxAgeFallback }) {
+  logger(`Configured caching of signing keys. Max: ${cacheMaxEntries} / Age: ${cacheMaxAge}${cacheMaxAgeFallback ? ` / Fallback: ${cacheMaxAgeFallback}` : ''}`);
+
+  const staleCache = new LRUCache({ max: cacheMaxEntries });
+  const getSigningKey = client.getSigningKey.bind(client);
+
+  const load = callbackify(async (kid) => {
+    try {
+      const key = await getSigningKey(kid);
+      staleCache.set(kid, { key, fetchedAt: Date.now() });
+      return key;
+    } catch (err) {
+      if (cacheMaxAgeFallback) {
+        const stale = staleCache.get(kid);
+        if (stale && (Date.now() - stale.fetchedAt) < (cacheMaxAge + cacheMaxAgeFallback)) {
+          logger(`Signing key for '${kid}' is stale but within fallback window, serving stale key`);
+          return stale.key;
+        }
+      }
+      throw err;
+    }
+  });
+
   return promisify(memoizer({
     hash: (kid) => kid,
-    load: callbackify(client.getSigningKey.bind(client)),
+    load,
     ttl: cacheMaxAge,
     max: cacheMaxEntries
   }));

tests/cache.tests.js

@@ -48,6 +48,93 @@ describe('JwksClient (cache)', () => {
         expect(scope.isDone()).not.ok;
       });
     });
+    describe('cacheMaxAgeFallback', () => {
+      const kid = 'NkFCNEE1NDFDNTQ5RTQ5OTE1QzRBMjYyMzY0NEJCQTJBMjJBQkZCMA';
+      const cacheMaxAge = 100;
+      const cacheMaxAgeFallback = 500;
+
+      it('should serve stale key when AS is down and within fallback window', async () => {
+        const scope = nock(jwksHost)
+          .get('/.well-known/jwks.json')
+          .once()
+          .reply(200, x5cSingle);
+
+        const client = new JwksClient({
+          cache: true,
+          cacheMaxAge,
+          cacheMaxAgeFallback,
+          jwksUri: `${jwksHost}/.well-known/jwks.json`
+        });
+
+        // First request - caches the key
+        const key1 = await client.getSigningKey(kid);
+        expect(key1.kid).to.equal(kid);
+
+        // AS goes down
+        nock(jwksHost).get('/.well-known/jwks.json').reply(500, 'Service Unavailable');
+
+        // Wait for cacheMaxAge to expire
+        await new Promise(resolve => setTimeout(resolve, cacheMaxAge + 10));
+
+        // Should serve stale key instead of throwing
+        const key2 = await client.getSigningKey(kid);
+        expect(key2.kid).to.equal(kid);
+        expect(scope.isDone()).ok;
+
+        nock.cleanAll();
+      });
+
+      it('should throw when AS is down and fallback window has also expired', async () => {
+        nock(jwksHost)
+          .get('/.well-known/jwks.json')
+          .once()
+          .reply(200, x5cSingle);
+
+        const client = new JwksClient({
+          cache: true,
+          cacheMaxAge,
+          cacheMaxAgeFallback: 50,
+          jwksUri: `${jwksHost}/.well-known/jwks.json`
+        });
+
+        // First request - caches the key
+        await client.getSigningKey(kid);
+
+        // AS goes down
+        nock(jwksHost).get('/.well-known/jwks.json').reply(500, 'Service Unavailable');
+
+        // Wait for both cacheMaxAge + cacheMaxAgeFallback to expire
+        await new Promise(resolve => setTimeout(resolve, cacheMaxAge + 50 + 20));
+
+        await expect(client.getSigningKey(kid)).to.eventually.be.rejected;
+
+        nock.cleanAll();
+      });
+
+      it('should not serve stale key when cacheMaxAgeFallback is not set', async () => {
+        nock(jwksHost)
+          .get('/.well-known/jwks.json')
+          .once()
+          .reply(200, x5cSingle);
+
+        const client = new JwksClient({
+          cache: true,
+          cacheMaxAge,
+          jwksUri: `${jwksHost}/.well-known/jwks.json`
+        });
+
+        await client.getSigningKey(kid);
+
+        nock(jwksHost).get('/.well-known/jwks.json').reply(500, 'Service Unavailable');
+
+        await new Promise(resolve => setTimeout(resolve, cacheMaxAge + 10));
+
+        await expect(client.getSigningKey(kid)).to.eventually.be.rejected;
+
+        nock.cleanAll();
+      });
+    });
+
     describe('should respect cacheMaxAge', () => {
       const kid = 'NkFCNEE1NDFDNTQ5RTQ5OTE1QzRBMjYyMzY0NEJCQTJBMjJBQkZCMA';
       const cacheMaxAge = 100;