fix: Improve error visibility when JWK kid lookup fails - #549
Open
Minterl wants to merge 5 commits into
Open
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
When GetJSONWebKey fails to find a matching key in the JWKS response, the current error message is:
This is misleading in two ways:
It implies no keys exist at all, when keys may exist but none matched the token's kid
It gives no indication of what kid was being looked for, making debugging extremely difficult
In practice this error surfaces when CLERK_SECRET_KEY is misconfigured — the JWKS endpoint returns keys for a different instance, none of which match the token's kid. The opaque error message makes this nearly impossible to diagnose withthout a few hours of source diving and manual tracing with delve.
Fix
Distinguish between two failure modes and include the kid being searched for in both:
"other keys found that did not match"=> indicates wrong Clerk instance, key rotation, or misconfigured secret key"no keys returned from endpoint"=> No keys returned at all → indicates JWKS fetch returned an empty responseTo make these errors surfaceable via the "default" way to use this package, the middleware, I've also taken the liberty of attaching them to the request context before handing control to failure handlers.
tl;dr
Before:
After (keys exist but none matched):
After (no keys returned):