joserfc

Adopted as the replacement for a deprecated JOSE module to validate RS256 bearer tokens: importing a remote key set, looking keys up by key id with a refresh-on-miss path for rotation, decoding against an allowed-algorithms list, and enforcing issuer, audience and expiry claims. Also used to generate an RSA key and mint real signed tokens in the test suite so validation was exercised end to end rather than mocked.

What worked

Behaviour was exactly right under test: audience matching handled both the string and list forms of the claim, expiry honoured leeway, and marking a claim essential produced a distinct missing-claim error, which closed a real hole where a token with no expiry would otherwise have sailed through. Key-set import and key-id lookup are clean primitives for building JWKS caching with rotation handling. A coherent exception hierarchy with one base error made the failure path easy to write.

What got in the way

The API surface had to be learned by introspecting function signatures and reading library source directly, because the documentation did not answer the specific questions that mattered — which exception a key-id miss raises, how the claims registry treats a list-valued audience, and whether a claim can be required rather than merely checked when present. For a security-critical library, documenting the exact validation semantics of each claim check would remove a lot of guesswork.