feat(backend): Add available kid to jwk-remote-missing error (#1816)

clerk · Oct 3, 2023 · fed24f1 · fed24f1
1 parent 65903d5
commit fed24f1
Show file tree

Hide file tree

Showing 3 changed files with 26 additions and 4 deletions.
diff --git a/.changeset/cool-planes-shake.md b/.changeset/cool-planes-shake.md
@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Improve the `jwk-remote-missing` error by adding the available JWK IDs to the error message. This way you can understand why the entry was not found and compare the available ones with other keys.
diff --git a/packages/backend/src/tokens/keys.test.ts b/packages/backend/src/tokens/keys.test.ts
@@ -189,10 +189,11 @@ export default (QUnit: QUnit) => {
     });
 
     test('throws an error when JWKS can not be fetched from Backend or Frontend API and cache updated less than 5 minutes ago', async assert => {
+      const kid = 'ins_whatever';
       try {
         await loadClerkJWKFromRemote({
           apiKey: 'deadbeef',
-          kid: 'ins_whatever',
+          kid,
         });
         assert.false(true);
       } catch (err) {
@@ -201,6 +202,9 @@ export default (QUnit: QUnit) => {
             reason: 'jwk-remote-missing',
             action: 'Contact support@clerk.com',
           });
+          assert.propContains(err, {
+            message: `Unable to find a signing key in JWKS that matches the kid='${kid}' of the provided session token. Please make sure that the __session cookie or the HTTP authorization header contain a Clerk-generated session JWT. The following kid are available: ${mockRsaJwkKid}, local`,
+          });
         } else {
           // This should never be reached. If it does, the suite should fail
           assert.false(true);
@@ -210,11 +214,12 @@ export default (QUnit: QUnit) => {
 
     test('throws an error when no JWK matches the provided kid', async assert => {
       fakeFetch.onCall(0).returns(jsonOk(mockJwks));
+      const kid = 'ins_whatever';
 
       try {
         await loadClerkJWKFromRemote({
           apiKey: 'deadbeef',
-          kid: 'ins_whatever',
+          kid,
         });
         assert.false(true);
       } catch (err) {
@@ -223,6 +228,9 @@ export default (QUnit: QUnit) => {
             reason: 'jwk-remote-missing',
             action: 'Contact support@clerk.com',
           });
+          assert.propContains(err, {
+            message: `Unable to find a signing key in JWKS that matches the kid='${kid}' of the provided session token. Please make sure that the __session cookie or the HTTP authorization header contain a Clerk-generated session JWT. The following kid are available: ${mockRsaJwkKid}, local`,
+          });
         } else {
           // This should never be reached. If it does, the suite should fail
           assert.false(true);

diff --git a/packages/backend/src/tokens/keys.ts b/packages/backend/src/tokens/keys.ts
@@ -23,6 +23,10 @@ function getFromCache(kid: string) {
   return cache[kid];
 }
 
+function getCacheValues() {
+  return Object.values(cache);
+}
+
 function setInCache(
   jwk: JsonWebKeyWithKid,
   jwksCacheTtlInMs: number = 1000 * 60 * 60, // 1 hour
@@ -144,7 +148,7 @@ export async function loadClerkJWKFromRemote({
       });
     }
 
-    const { keys }: { keys: JsonWebKeyWithKid[] } = await callWithRetry(fetcher);
+    const { keys } = await callWithRetry<{ keys: JsonWebKeyWithKid[] }>(fetcher);
 
     if (!keys || !keys.length) {
       throw new TokenVerificationError({
@@ -160,9 +164,14 @@ export async function loadClerkJWKFromRemote({
   const jwk = getFromCache(kid);
 
   if (!jwk) {
+    const cacheValues = getCacheValues();
+    const jwkKeys = cacheValues.map(jwk => jwk.kid).join(', ');
+
     throw new TokenVerificationError({
       action: TokenVerificationErrorAction.ContactSupport,
-      message: `Unable to find a signing key in JWKS that matches the kid='${kid}' of the provided session token. Please make sure that the __session cookie or the HTTP authorization header contain a Clerk-generated session JWT.`,
+      message: `Unable to find a signing key in JWKS that matches the kid='${kid}' of the provided session token. Please make sure that the __session cookie or the HTTP authorization header contain a Clerk-generated session JWT.${
+        jwkKeys ? ` The following kid are available: ${jwkKeys}` : ''
+      }`,
       reason: TokenVerificationErrorReason.RemoteJWKMissing,
     });
   }