jwt 2.4.1 → 2.9.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6e7f3474ee58d51ca5646f48ca28bf669b40a4b7676cbe7211597ca6ae69f672
-  data.tar.gz: 570e6930c9094afea40ea8e8a6a7c9b3293890b121893f5148914b0a8e7d11f8
+  metadata.gz: ce035519b0df530866af63d7dd6cb267490700e9458fc9c32fb0bb15be446f6e
+  data.tar.gz: 94fd6a38f0e3c91407b04aa254d568e113877e7dcdcb4b923c28b6a320587119
 SHA512:
-  metadata.gz: 3249529ec6bacc8e655e2830949af61c10e235a569f9dc67d3880335d5939b8afc56c180145d3e02dd09744288d50c31547338e105cf55ae4e0fbe237eb2a0e8
-  data.tar.gz: dd415314a7bd048d8b2b5b630d5b7011128932bf207dc785ac6154748aff68836a1c39e766dc176e225c643fc406fe9fdc5c510b36dc939e36722e327d8fe92f
+  metadata.gz: aaf541769af85436646e45a61e0f3a57d75a88e640f4a811eff35d8be61285dc77b1741e79147cf435fed5b51519863fc027722d43805c3457a159d8e235f568
+  data.tar.gz: f548c7bcfac5c31520ba0a1cc1b5dd546cf600277667109e7c33fde167138a3a29a930cf127cc51a7546e5b4c14e5e093a8279949107cd0d0062d016067a1723

data/CHANGELOG.md

@@ -1,31 +1,194 @@
 # Changelog
-## [v2.4.1](https://github.com/jwt/ruby-jwt/tree/v2.4.1) (2022-06-07)
+
+## Upcoming breaking changes
+
+Notable changes in the upcoming **version 3.0**:
+
+- The indirect dependency to [rbnacl](https://github.com/RubyCrypto/rbnacl) will be removed:
+  - Support for the nonstandard SHA512256 algorithm will be removed.
+  - Support for Ed25519 will be moved to a [separate gem](https://github.com/anakinj/jwt-eddsa) for better dependency handling.
+
+- Base64 decoding will no longer fallback on the looser RFC 2045.
+
+- Claim verification has been [split into separate classes](https://github.com/jwt/ruby-jwt/pull/605) and has [a new api](https://github.com/jwt/ruby-jwt/pull/626) and lead to the following deprecations:
+  - The `::JWT::ClaimsValidator` class will be removed in favor of the functionality provided by `::JWT::Claims`.
+  - The `::JWT::Claims::verify!` method will be removed in favor of `::JWT::Claims::verify_payload!`.
+  - The `::JWT::JWA.create` method will be removed. No recommended alternatives.
+  - The `::JWT::Verify` class will be removed in favor of the functionality provided by `::JWT::Claims`.
+  - Calling `::JWT::Claims::Numeric.new` with a payload will be removed in favor of `::JWT::Claims::verify_payload!(payload, :numeric)`.
+  - Calling `::JWT::Claims::Numeric.verify!` with a payload will be removed in favor of `::JWT::Claims::verify_payload!(payload, :numeric)`.
+
+- The internal algorithms were [restructured](https://github.com/jwt/ruby-jwt/pull/607) to support extensions from separate libraries. The changes lead to a few deprecations and new requirements:
+  - The `sign` and `verify` static methods on all the algorithms (`::JWT::JWA`) will be removed.
+  - Custom algorithms are expected to include the `JWT::JWA::SigningAlgorithm` module.
+
+## [v2.9.3](https://github.com/jwt/ruby-jwt/tree/v2.9.3) (2024-10-03)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.9.2...v2.9.3)
+
+**Fixes and enhancements:**
+
+- Return truthy value for `::JWT::ClaimsValidator#validate!` and `::JWT::Verify.verify_claims` [#628](https://github.com/jwt/ruby-jwt/pull/628) ([@anakinj](https://github.com/anakinj))
+
+## [v2.9.2](https://github.com/jwt/ruby-jwt/tree/v2.9.2) (2024-10-03)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.9.1...v2.9.2)
+
+**Features:**
+
+- Standalone claim verification interface [#626](https://github.com/jwt/ruby-jwt/pull/626) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Updated README to correctly document `OpenSSL::HMAC` documentation [#617](https://github.com/jwt/ruby-jwt/pull/617) ([@aedryan](https://github.com/aedryan))
+- Verify JWT header format [#622](https://github.com/jwt/ruby-jwt/pull/622) ([@304](https://github.com/304))
+- Bring back `::JWT::ClaimsValidator`, `::JWT::Verify` and a few other removed interfaces for preserved backwards compatibility [#624](https://github.com/jwt/ruby-jwt/pull/624) ([@anakinj](https://github.com/anakinj))
+
+## [v2.9.1](https://github.com/jwt/ruby-jwt/tree/v2.9.1) (2024-09-23)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.9.0...v2.9.1)
+
+**Fixes and enhancements:**
+
+- Fix regression in `iss` and `aud` claim validation [#619](https://github.com/jwt/ruby-jwt/pull/619) ([@anakinj](https://github.com/anakinj))
+
+## [v2.9.0](https://github.com/jwt/ruby-jwt/tree/v2.9.0) (2024-09-15)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.8.2...v2.9.0)
+
+**Features:**
+
+- Build and push gem using a GH action [#612](https://github.com/jwt/ruby-jwt/pull/612) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Refactor claim validators into their own classes [#605](https://github.com/jwt/ruby-jwt/pull/605) ([@anakinj](https://github.com/anakinj), [@MatteoPierro](https://github.com/MatteoPierro))
+- Allow extending available algorithms [#607](https://github.com/jwt/ruby-jwt/pull/607) ([@anakinj](https://github.com/anakinj))
+- Do not include the EdDSA algorithm if rbnacl not available [#613](https://github.com/jwt/ruby-jwt/pull/613) ([@anakinj](https://github.com/anakinj))
+
+## [v2.8.2](https://github.com/jwt/ruby-jwt/tree/v2.8.2) (2024-06-18)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.8.1...v2.8.2)
+
+**Fixes and enhancements:**
+
+- Print deprecation warnings only on when token decoding succeeds [#600](https://github.com/jwt/ruby-jwt/pull/600) ([@anakinj](https://github.com/anakinj))
+- Unify code style [#602](https://github.com/jwt/ruby-jwt/pull/602) ([@anakinj](https://github.com/anakinj))
+
+## [v2.8.1](https://github.com/jwt/ruby-jwt/tree/v2.8.1) (2024-02-29)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.8.0...v2.8.1)
+
+**Features:**
+
+- Configurable base64 decode behaviour [#589](https://github.com/jwt/ruby-jwt/pull/589) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Output deprecation warnings once [#589](https://github.com/jwt/ruby-jwt/pull/589) ([@anakinj](https://github.com/anakinj))
+
+## [v2.8.0](https://github.com/jwt/ruby-jwt/tree/v2.8.0) (2024-02-17)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.7.1...v2.8.0)
+
+**Features:**
+
+- Updated rubocop to 1.56 [#573](https://github.com/jwt/ruby-jwt/pull/573) ([@anakinj](https://github.com/anakinj))
+- Run CI on Ruby 3.3 [#577](https://github.com/jwt/ruby-jwt/pull/577) ([@anakinj](https://github.com/anakinj))
+- Deprecation warning added for the HMAC algorithm HS512256 (HMAC-SHA-512 truncated to 256-bits) [#575](https://github.com/jwt/ruby-jwt/pull/575) ([@anakinj](https://github.com/anakinj))
+- Stop using RbNaCl for standard HMAC algorithms [#575](https://github.com/jwt/ruby-jwt/pull/575) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Fix signature has expired error if payload is a string [#555](https://github.com/jwt/ruby-jwt/pull/555) ([@GobinathAL](https://github.com/GobinathAL))
+- Fix key base equality and spaceship operators [#569](https://github.com/jwt/ruby-jwt/pull/569) ([@magneland](https://github.com/magneland))
+- Remove explicit base64 require from x5c_key_finder [#580](https://github.com/jwt/ruby-jwt/pull/580) ([@anakinj](https://github.com/anakinj))
+- Performance improvements and cleanup of tests [#581](https://github.com/jwt/ruby-jwt/pull/581) ([@anakinj](https://github.com/anakinj))
+- Repair EC x/y coordinates when importing JWK [#585](https://github.com/jwt/ruby-jwt/pull/585) ([@julik](https://github.com/julik))
+- Explicit dependency to the base64 gem [#582](https://github.com/jwt/ruby-jwt/pull/582) ([@anakinj](https://github.com/anakinj))
+- Deprecation warning for decoding content not compliant with RFC 4648 [#582](https://github.com/jwt/ruby-jwt/pull/582) ([@anakinj](https://github.com/anakinj))
+- Algorithms moved under the `::JWT::JWA` module ([@anakinj](https://github.com/anakinj))
+
+## [v2.7.1](https://github.com/jwt/ruby-jwt/tree/v2.8.0) (2023-06-09)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.7.0...v2.7.1)
+
+**Fixes and enhancements:**
+
+- Handle invalid algorithm when decoding JWT [#559](https://github.com/jwt/ruby-jwt/pull/559) ([@nataliastanko](https://github.com/nataliastanko))
+- Do not raise error when verifying bad HMAC signature [#563](https://github.com/jwt/ruby-jwt/pull/563) ([@hieuk09](https://github.com/hieuk09))
+
+## [v2.7.0](https://github.com/jwt/ruby-jwt/tree/v2.7.0) (2023-02-01)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.6.0...v2.7.0)
+
+**Features:**
+
+- Support OKP (Ed25519) keys for JWKs [#540](https://github.com/jwt/ruby-jwt/pull/540) ([@anakinj](https://github.com/anakinj))
+- JWK Sets can now be used for tokens with nil kid [#543](https://github.com/jwt/ruby-jwt/pull/543) ([@bellebaum](https://github.com/bellebaum))
 
 **Fixes and enhancements:**
-- Raise JWT::DecodeError on invalid signature [\#484](https://github.com/jwt/ruby-jwt/pull/484) ([@freakyfelt!](https://github.com/freakyfelt!)).
+
+- Fix issue with multiple keys returned by keyfinder and multiple allowed algorithms [#545](https://github.com/jwt/ruby-jwt/pull/545) ([@mpospelov](https://github.com/mpospelov))
+- Non-string `kid` header values are now rejected [#543](https://github.com/jwt/ruby-jwt/pull/543) ([@bellebaum](https://github.com/bellebaum))
+
+## [v2.6.0](https://github.com/jwt/ruby-jwt/tree/v2.6.0) (2022-12-22)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.5.0...v2.6.0)
+
+**Features:**
+
+- Support custom algorithms by passing algorithm objects [#512](https://github.com/jwt/ruby-jwt/pull/512) ([@anakinj](https://github.com/anakinj))
+- Support descriptive (not key related) JWK parameters [#520](https://github.com/jwt/ruby-jwt/pull/520) ([@bellebaum](https://github.com/bellebaum))
+- Support for JSON Web Key Sets [#525](https://github.com/jwt/ruby-jwt/pull/525) ([@bellebaum](https://github.com/bellebaum))
+- Support HMAC keys over 32 chars when using RbNaCl [#521](https://github.com/jwt/ruby-jwt/pull/521) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+
+- Raise descriptive error on empty hmac_secret and OpenSSL 3.0/openssl gem <3.0.1 [#530](https://github.com/jwt/ruby-jwt/pull/530) ([@jonmchan](https://github.com/jonmchan))
+
+## [v2.5.0](https://github.com/jwt/ruby-jwt/tree/v2.5.0) (2022-08-25)
+
+[Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.4.1...v2.5.0)
+
+**Features:**
+
+- Support JWK thumbprints as key ids [#481](https://github.com/jwt/ruby-jwt/pull/481) ([@anakinj](https://github.com/anakinj))
+- Support OpenSSL >= 3.0 [#496](https://github.com/jwt/ruby-jwt/pull/496) ([@anakinj](https://github.com/anakinj))
+
+**Fixes and enhancements:**
+- Bring back the old Base64 (RFC2045) deocode mechanisms [#488](https://github.com/jwt/ruby-jwt/pull/488) ([@anakinj](https://github.com/anakinj))
+- Rescue RbNaCl exception for EdDSA wrong key [#491](https://github.com/jwt/ruby-jwt/pull/491) ([@n-studio](https://github.com/n-studio))
+- New parameter name for cases when kid is not found using JWK key loader proc [#501](https://github.com/jwt/ruby-jwt/pull/501) ([@anakinj](https://github.com/anakinj))
+- Fix NoMethodError when a 2 segment token is missing 'alg' header [#502](https://github.com/jwt/ruby-jwt/pull/502) ([@cmrd-senya](https://github.com/cmrd-senya))
+
+## [v2.4.1](https://github.com/jwt/ruby-jwt/tree/v2.4.1) (2022-06-07)
 
 [Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.4.0...v2.4.1)
 
+**Fixes and enhancements:**
+- Raise JWT::DecodeError on invalid signature [\#484](https://github.com/jwt/ruby-jwt/pull/484) ([@freakyfelt!](https://github.com/freakyfelt!))
+
 ## [v2.4.0](https://github.com/jwt/ruby-jwt/tree/v2.4.0) (2022-06-06)
 
 [Full Changelog](https://github.com/jwt/ruby-jwt/compare/v2.3.0...v2.4.0)
 
 **Features:**
 
-- Dropped support for Ruby 2.5 and older [#453](https://github.com/jwt/ruby-jwt/pull/453) - [@anakinj](https://github.com/anakinj).
-- Use Ruby built-in url-safe base64 methods [#454](https://github.com/jwt/ruby-jwt/pull/454) - [@bdewater](https://github.com/bdewater).
-- Updated rubocop to 1.23.0 [#457](https://github.com/jwt/ruby-jwt/pull/457) - [@anakinj](https://github.com/anakinj).
-- Add x5c header key finder [#338](https://github.com/jwt/ruby-jwt/pull/338) - [@bdewater](https://github.com/bdewater).
-- Author driven changelog process [#463](https://github.com/jwt/ruby-jwt/pull/463) - [@anakinj](https://github.com/anakinj).
-- Allow regular expressions and procs to verify issuer [\#437](https://github.com/jwt/ruby-jwt/pull/437) ([rewritten](https://github.com/rewritten)).
-- Add Support to be able to verify from multiple keys [\#425](https://github.com/jwt/ruby-jwt/pull/425) ([ritikesh](https://github.com/ritikesh)).
+- Dropped support for Ruby 2.5 and older [#453](https://github.com/jwt/ruby-jwt/pull/453) - ([@anakinj](https://github.com/anakinj))
+- Use Ruby built-in url-safe base64 methods [#454](https://github.com/jwt/ruby-jwt/pull/454) - ([@bdewater](https://github.com/bdewater))
+- Updated rubocop to 1.23.0 [#457](https://github.com/jwt/ruby-jwt/pull/457) - ([@anakinj](https://github.com/anakinj))
+- Add x5c header key finder [#338](https://github.com/jwt/ruby-jwt/pull/338) - ([@bdewater](https://github.com/bdewater))
+- Author driven changelog process [#463](https://github.com/jwt/ruby-jwt/pull/463) - ([@anakinj](https://github.com/anakinj))
+- Allow regular expressions and procs to verify issuer [\#437](https://github.com/jwt/ruby-jwt/pull/437) ([rewritten](https://github.com/rewritten))
+- Add Support to be able to verify from multiple keys [\#425](https://github.com/jwt/ruby-jwt/pull/425) ([ritikesh](https://github.com/ritikesh))
 
 **Fixes and enhancements:**
-- Readme: Typo fix re MissingRequiredClaim [\#451](https://github.com/jwt/ruby-jwt/pull/451) ([antonmorant](https://github.com/antonmorant)).
-- Fix RuboCop TODOs [\#476](https://github.com/jwt/ruby-jwt/pull/476) ([typhoon2099](https://github.com/typhoon2099)).
-- Make specific algorithms in README linkable [\#472](https://github.com/jwt/ruby-jwt/pull/472) ([milieu](https://github.com/milieu)).
-- Update note about supported JWK types [\#475](https://github.com/jwt/ruby-jwt/pull/475) ([dpashkevich](https://github.com/dpashkevich)).
-- Create CODE\_OF\_CONDUCT.md [\#449](https://github.com/jwt/ruby-jwt/pull/449) ([loic5](https://github.com/loic5)).
+- Readme: Typo fix re MissingRequiredClaim [\#451](https://github.com/jwt/ruby-jwt/pull/451) ([antonmorant](https://github.com/antonmorant))
+- Fix RuboCop TODOs [\#476](https://github.com/jwt/ruby-jwt/pull/476) ([typhoon2099](https://github.com/typhoon2099))
+- Make specific algorithms in README linkable [\#472](https://github.com/jwt/ruby-jwt/pull/472) ([milieu](https://github.com/milieu))
+- Update note about supported JWK types [\#475](https://github.com/jwt/ruby-jwt/pull/475) ([dpashkevich](https://github.com/dpashkevich))
+- Create CODE\_OF\_CONDUCT.md [\#449](https://github.com/jwt/ruby-jwt/pull/449) ([loic5](https://github.com/loic5))
 
 ## [v2.3.0](https://github.com/jwt/ruby-jwt/tree/v2.3.0) (2021-10-03)
 

data/CONTRIBUTING.md

@@ -12,19 +12,19 @@ git remote add upstream https://github.com/jwt/ruby-jwt
 
 ## Create a branch for your implementation
 
-Make sure you have the latest upstream master branch of the project.
+Make sure you have the latest upstream main branch of the project.
 
 ```
 git fetch --all
-git checkout master
-git rebase upstream/master
-git push origin master
+git checkout main
+git rebase upstream/main
+git push origin main
 git checkout -b fix-a-little-problem
 ```
 
 ## Running the tests and linter
 
-Before you start with your implementation make sure you are able to get a succesful test run with the current revision.
+Before you start with your implementation make sure you are able to get a successful test run with the current revision.
 
 The tests are written with rspec and [Appraisal](https://github.com/thoughtbot/appraisal) is used to ensure compatibility with 3rd party dependencies providing cryptographic features.
 
@@ -78,12 +78,12 @@ A maintainer will review and probably merge you changes when time allows, be pat
 
 ## Keeping your branch up-to-date
 
-It's recommended that you keep your branch up-to-date by rebasing to the upstream master.
+It's recommended that you keep your branch up-to-date by rebasing to the upstream main.
 
 ```
 git fetch upstream
 git checkout fix-a-little-problem
-git rebase upstream/master
+git rebase upstream/main
 git push origin fix-a-little-problem -f
 ```
 

data/README.md

@@ -1,18 +1,17 @@
 # JWT
 
 [![Gem Version](https://badge.fury.io/rb/jwt.svg)](https://badge.fury.io/rb/jwt)
-[![Build Status](https://github.com/jwt/ruby-jwt/workflows/test/badge.svg?branch=master)](https://github.com/jwt/ruby-jwt/actions)
+[![Build Status](https://github.com/jwt/ruby-jwt/workflows/test/badge.svg?branch=main)](https://github.com/jwt/ruby-jwt/actions)
 [![Code Climate](https://codeclimate.com/github/jwt/ruby-jwt/badges/gpa.svg)](https://codeclimate.com/github/jwt/ruby-jwt)
 [![Test Coverage](https://codeclimate.com/github/jwt/ruby-jwt/badges/coverage.svg)](https://codeclimate.com/github/jwt/ruby-jwt/coverage)
 [![Issue Count](https://codeclimate.com/github/jwt/ruby-jwt/badges/issue_count.svg)](https://codeclimate.com/github/jwt/ruby-jwt)
-[![SourceLevel](https://app.sourcelevel.io/github/jwt/-/ruby-jwt.svg)](https://app.sourcelevel.io/github/jwt/-/ruby-jwt)
 
 A ruby implementation of the [RFC 7519 OAuth JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) standard.
 
 If you have further questions related to development or usage, join us: [ruby-jwt google group](https://groups.google.com/forum/#!forum/ruby-jwt).
 
 ## Announcements
-* Ruby 2.4 support is going to be dropped in version 2.4.0
+* Ruby 2.4 support was dropped in version 2.4.0
 * Ruby 1.9.3 support was dropped at December 31st, 2016.
 * Version 1.5.3 yanked. See: [#132](https://github.com/jwt/ruby-jwt/issues/132) and [#133](https://github.com/jwt/ruby-jwt/issues/133)
 
@@ -44,6 +43,23 @@ The JWT spec supports NONE, HMAC, RSASSA, ECDSA and RSASSA-PSS algorithms for cr
 
 See: [ JSON Web Algorithms (JWA) 3.1. "alg" (Algorithm) Header Parameter Values for JWS](https://tools.ietf.org/html/rfc7518#section-3.1)
 
+### Deprecation warnings
+
+Deprecation warnings are logged once (`:once` option) by default to avoid spam in logs. Other options are `:silent` to completely silence warnings and `:warn` to log every time a deprecated path is executed.
+
+```ruby
+  JWT.configuration.deprecation_warnings = :warn # default is :once
+```
+
+### Base64 decoding
+
+In the past the gem has been supporting the Base64 decoding specified in [RFC2045](https://www.rfc-editor.org/rfc/rfc2045) allowing newlines and blanks in the base64 encoded payload. In future versions base64 decoding will be stricter and only comply to [RFC4648](https://www.rfc-editor.org/rfc/rfc4648).
+
+The stricter base64 decoding when processing tokens can be done via the `strict_base64_decoding` configuration accessor.
+```ruby
+  JWT.configuration.strict_base64_decoding = true # default is false
+```
+
 ### **NONE**
 
 * none - unsigned token
@@ -73,12 +89,11 @@ puts decoded_token
 ### **HMAC**
 
 * HS256 - HMAC using SHA-256 hash algorithm
-* HS512256 - HMAC using SHA-512-256 hash algorithm (only available with RbNaCl; see note below)
 * HS384 - HMAC using SHA-384 hash algorithm
 * HS512 - HMAC using SHA-512 hash algorithm
 
 ```ruby
-# The secret must be a string. A JWT::DecodeError will be raised if it isn't provided.
+# The secret must be a string. With OpenSSL 3.0/openssl gem `<3.0.1`, JWT::DecodeError will be raised if it isn't provided.
 hmac_secret = 'my$ecretK3y'
 
 token = JWT.encode payload, hmac_secret, 'HS256'
@@ -96,12 +111,6 @@ decoded_token = JWT.decode token, hmac_secret, true, { algorithm: 'HS256' }
 puts decoded_token
 ```
 
-Note: If [RbNaCl](https://github.com/cryptosphere/rbnacl) is loadable, ruby-jwt will use it for HMAC-SHA256, HMAC-SHA512-256, and HMAC-SHA512. RbNaCl enforces a maximum key size of 32 bytes for these algorithms.
-
-[RbNaCl](https://github.com/cryptosphere/rbnacl) requires
-[libsodium](https://github.com/jedisct1/libsodium), it can be installed
-on MacOS with `brew install libsodium`.
-
 ### **RSA**
 
 * RS256 - RSA using SHA-256 hash algorithm
@@ -135,17 +144,14 @@ puts decoded_token
 * ES256K - ECDSA using P-256K and SHA-256
 
 ```ruby
-ecdsa_key = OpenSSL::PKey::EC.new 'prime256v1'
-ecdsa_key.generate_key
-ecdsa_public = OpenSSL::PKey::EC.new ecdsa_key
-ecdsa_public.private_key = nil
+ecdsa_key = OpenSSL::PKey::EC.generate('prime256v1')
 
 token = JWT.encode payload, ecdsa_key, 'ES256'
 
 # eyJhbGciOiJFUzI1NiJ9.eyJkYXRhIjoidGVzdCJ9.AlLW--kaF7EX1NMX9WJRuIW8NeRJbn2BLXHns7Q5TZr7Hy3lF6MOpMlp7GoxBFRLISQ6KrD0CJOrR8aogEsPeg
 puts token
 
-decoded_token = JWT.decode token, ecdsa_public, true, { algorithm: 'ES256' }
+decoded_token = JWT.decode token, ecdsa_key, true, { algorithm: 'ES256' }
 
 # Array
 # [
@@ -163,7 +169,7 @@ In order to use this algorithm you need to add the `RbNaCl` gem to you `Gemfile`
 gem 'rbnacl'
 ```
 
-For more detailed installation instruction check the official [repository](https://github.com/cryptosphere/rbnacl) on GitHub.
+For more detailed installation instruction check the official [repository](https://github.com/RubyCrypto/rbnacl) on GitHub.
 
 * ED25519
 
@@ -186,7 +192,7 @@ decoded_token = JWT.decode token, public_key, true, { algorithm: 'ED25519' }
 
 ### **RSASSA-PSS**
 
-In order to use this algorithm you need to add the `openssl` gem to you `Gemfile` with a version greater or equal to `2.1`.
+In order to use this algorithm you need to add the `openssl` gem to your `Gemfile` with a version greater or equal to `2.1`.
 
 ```ruby
 gem 'openssl', '~> 2.1'
@@ -215,6 +221,37 @@ decoded_token = JWT.decode token, rsa_public, true, { algorithm: 'PS256' }
 puts decoded_token
 ```
 
+### **Custom algorithms**
+
+When encoding or decoding a token, you can pass in a custom object through the `algorithm` option to handle signing or verification. This custom object must include or extend the `JWT::JWA::SigningAlgorithm` module and implement certain methods:
+
+- For decoding/verifying: The object must implement the methods `alg` and `verify`.
+- For encoding/signing: The object must implement the methods `alg` and `sign`.
+
+For customization options check the details from `JWT::JWA::SigningAlgorithm`.
+
+
+```ruby
+module CustomHS512Algorithm
+  extend JWT::JWA::SigningAlgorithm
+
+  def self.alg
+    'HS512'
+  end
+
+  def self.sign(data:, signing_key:)
+    OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha512'), signing_key, data)
+  end
+
+  def self.verify(data:, signature:, verification_key:)
+    ::OpenSSL.secure_compare(sign(data: data, signing_key: verification_key), signature)
+  end
+end
+
+token = ::JWT.encode({'pay' => 'load'}, 'secret', CustomHS512Algorithm)
+payload, header = ::JWT.decode(token, 'secret', true, algorithm: CustomHS512Algorithm)
+```
+
 ## Support for reserved claim names
 JSON Web Token defines some reserved claim names and defines how they should be
 used. JWT supports these reserved claim names:
@@ -493,6 +530,24 @@ rescue JWT::InvalidSubError
 end
 ```
 
+### Standalone claim verification
+
+The JWT claim verifications can be used to verify any Hash to include expected keys and values.
+
+A few example on verifying the claims for a payload:
+```ruby
+JWT::Claims.verify_payload!({"exp" => Time.now.to_i + 10}, :numeric, :exp)
+JWT::Claims.valid_payload?({"exp" => Time.now.to_i + 10}, :exp)
+# => true
+JWT::Claims.payload_errors({"exp" => Time.now.to_i - 10}, :exp)
+# => [#<struct JWT::Claims::Error message="Signature has expired">]
+JWT::Claims.verify_payload!({"exp" => Time.now.to_i - 10}, exp: { leeway: 11})
+
+JWT::Claims.verify_payload!({"exp" => Time.now.to_i + 10, "sub" => "subject"}, :exp, sub: "subject")
+```
+
+
+
 ### Finding a Key
 
 To dynamically find the key for verifying the JWT signature, pass a block to the decode block. The block receives headers and the original payload as parameters. It should return with the key to verify the signature that was used to sign the JWT.
@@ -538,7 +593,7 @@ crls = crl_uris.map do |uri|
 end
 
 begin
-  JWT.decode(token, nil, true, { x5c: { root_certificates: root_certificates, crls: crls })
+  JWT.decode(token, nil, true, { x5c: { root_certificates: root_certificates, crls: crls } })
 rescue JWT::DecodeError
   # Handle error, e.g. x5c header certificate revoked or expired
 end
@@ -546,22 +601,62 @@ end
 
 ### JSON Web Key (JWK)
 
-JWK is a JSON structure representing a cryptographic key. Currently only supports RSA, EC and HMAC keys.
+JWK is a JSON structure representing a cryptographic key. This gem currently supports RSA, EC, OKP and HMAC keys. OKP support requires [RbNaCl](https://github.com/RubyCrypto/rbnacl) and currently only supports the Ed25519 curve.
+
+To encode a JWT using your JWK:
+
+```ruby
+optional_parameters = { kid: 'my-kid', use: 'sig', alg: 'RS512' }
+jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), optional_parameters)
+
+# Encoding
+payload = { data: 'data' }
+token = JWT.encode(payload, jwk.signing_key, jwk[:alg], kid: jwk[:kid])
+
+# JSON Web Key Set for advertising your signing keys
+jwks_hash = JWT::JWK::Set.new(jwk).export
+```
+
+To decode a JWT using a trusted entity's JSON Web Key Set (JWKS):
 
 ```ruby
-jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), "optional-kid")
-payload, headers = { data: 'data' }, { kid: jwk.kid }
+jwks = JWT::JWK::Set.new(jwks_hash)
+jwks.filter! {|key| key[:use] == 'sig' } # Signing keys only!
+algorithms = jwks.map { |key| key[:alg] }.compact.uniq
+JWT.decode(token, nil, true, algorithms: algorithms, jwks: jwks)
+```
+
+
+The `jwks` option can also be given as a lambda that evaluates every time a kid is resolved.
+This can be used to implement caching of remotely fetched JWK Sets.
 
-token = JWT.encode(payload, jwk.keypair, 'RS512', headers)
+If the requested `kid` is not found from the given set the loader will be called a second time with the `kid_not_found` option set to `true`.
+The application can choose to implement some kind of JWK cache invalidation or other mechanism to handle such cases.
 
-# The jwk loader would fetch the set of JWKs from a trusted source
-jwk_loader = ->(options) do
-  @cached_keys = nil if options[:invalidate] # need to reload the keys
-  @cached_keys ||= { keys: [jwk.export] }
+Tokens without a specified `kid` are rejected by default.
+This behaviour may be overwritten by setting the `allow_nil_kid` option for `decode` to `true`.
+
+```ruby
+jwks_loader = ->(options) do
+  # The jwk loader would fetch the set of JWKs from a trusted source.
+  # To avoid malicious requests triggering cache invalidations there needs to be
+  # some kind of grace time or other logic for determining the validity of the invalidation.
+  # This example only allows cache invalidations every 5 minutes.
+  if options[:kid_not_found] && @cache_last_update < Time.now.to_i - 300
+    logger.info("Invalidating JWK cache. #{options[:kid]} not found from previous cache")
+    @cached_keys = nil
+  end
+  @cached_keys ||= begin
+    @cache_last_update = Time.now.to_i
+    # Replace with your own JWKS fetching routine
+    jwks = JWT::JWK::Set.new(jwks_hash)
+    jwks.select! { |key| key[:use] == 'sig' } # Signing Keys only
+    jwks
+  end
 end
 
 begin
-  JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwk_loader})
+  JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwks_loader })
 rescue JWT::JWKError
   # Handle problems with the provided JWKs
 rescue JWT::DecodeError
@@ -569,26 +664,74 @@ rescue JWT::DecodeError
 end
 ```
 
-or by passing JWK as a simple Hash
+### Importing and exporting JSON Web Keys
 
-```
-jwks = { keys: [{ ... }] } # keys accepts both of string and symbol
-JWT.decode(token, nil, true, { algorithms: ['RS512'], jwks: jwks})
+The ::JWT::JWK class can be used to import both JSON Web Keys and OpenSSL keys
+and export to either format with and without the private key included.
+
+To include the private key in the export pass the `include_private` parameter to the export method.
+
+```ruby
+# Import a JWK Hash (showing an HMAC example)
+jwk = JWT::JWK.new({ kty: 'oct', k: 'my-secret', kid: 'my-kid' })
+
+# Import an OpenSSL key
+# You can optionally add descriptive parameters to the JWK
+desc_params = { kid: 'my-kid', use: 'sig' }
+jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), desc_params)
+
+# Export as JWK Hash (public key only by default)
+jwk_hash = jwk.export
+jwk_hash_with_private_key = jwk.export(include_private: true)
+
+# Export as OpenSSL key
+public_key = jwk.verify_key
+private_key = jwk.signing_key if jwk.private?
+
+# You can also import and export entire JSON Web Key Sets
+jwks_hash = { keys: [{ kty: 'oct', k: 'my-secret', kid: 'my-kid' }] }
+jwks = JWT::JWK::Set.new(jwks_hash)
+jwks_hash = jwks.export
 ```
 
-### Importing and exporting JSON Web Keys
+### Key ID (kid) and JWKs
 
-The ::JWT::JWK class can be used to import and export both the public key (default behaviour) and the private key. To include the private key in the export pass the `include_private` parameter to the export method.
+The key id (kid) generation in the gem is a custom algorithm and not based on any standards.
+To use a standardized JWK thumbprint (RFC 7638) as the kid for JWKs a generator type can be specified in the global configuration
+or can be given to the JWK instance on initialization.
 
 ```ruby
-jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048))
+JWT.configuration.jwk.kid_generator_type = :rfc7638_thumbprint
+# OR
+JWT.configuration.jwk.kid_generator = ::JWT::JWK::Thumbprint
+# OR
+jwk = JWT::JWK.new(OpenSSL::PKey::RSA.new(2048), nil, kid_generator: ::JWT::JWK::Thumbprint)
 
 jwk_hash = jwk.export
-jwk_hash_with_private_key = jwk.export(include_private: true)
+
+thumbprint_as_the_kid = jwk_hash[:kid]
 ```
 
-## How to contribute
+# Development and testing
 
+The tests are written with rspec. [Appraisal](https://github.com/thoughtbot/appraisal) is used to ensure compatibility with 3rd party dependencies providing cryptographic features.
+
+```bash
+bundle install
+bundle exec appraisal rake test
+```
+
+# Releasing
+
+To cut a new release adjust the [version.rb](lib/jwt/version.rb) and [CHANGELOG](CHANGELOG.md) with desired version numbers and dates and commit the changes. Tag the release with the version number using the following command:
+
+```bash
+rake release:source_control_push
+```
+
+This will tag a new version an trigger a [GitHub action](.github/workflows/push_gem.yml) that eventually will push the gem to rubygems.org.
+
+## How to contribute
 See [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Contributors

data/lib/jwt/base64.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module JWT
+  # Base64 encoding and decoding
+  class Base64
+    class << self
+      # Encode a string with URL-safe Base64 complying with RFC 4648 (not padded).
+      def url_encode(str)
+        ::Base64.urlsafe_encode64(str, padding: false)
+      end
+
+      # Decode a string with URL-safe Base64 complying with RFC 4648.
+      # Deprecated support for RFC 2045 remains for now. ("All line breaks or other characters not found in Table 1 must be ignored by decoding software")
+      def url_decode(str)
+        ::Base64.urlsafe_decode64(str)
+      rescue ArgumentError => e
+        raise unless e.message == 'invalid base64'
+        raise Base64DecodeError, 'Invalid base64 encoding' if JWT.configuration.strict_base64_decoding
+
+        loose_urlsafe_decode64(str).tap do
+          Deprecations.warning('Invalid base64 input detected, could be because of invalid padding, trailing whitespaces or newline chars. Graceful handling of invalid input will be dropped in the next major version of ruby-jwt', only_if_valid: true)
+        end
+      end
+
+      def loose_urlsafe_decode64(str)
+        str += '=' * (4 - str.length.modulo(4))
+        ::Base64.decode64(str.tr('-_', '+/'))
+      end
+    end
+  end
+end

data/lib/jwt/claims/audience.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module JWT
+  module Claims
+    class Audience
+      def initialize(expected_audience:)
+        @expected_audience = expected_audience
+      end
+
+      def verify!(context:, **_args)
+        aud = context.payload['aud']
+        raise JWT::InvalidAudError, "Invalid audience. Expected #{expected_audience}, received #{aud || '<none>'}" if ([*aud] & [*expected_audience]).empty?
+      end
+
+      private
+
+      attr_reader :expected_audience
+    end
+  end
+end