pq_crypto-jwt 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ded8bedea5417580ef9a3199f47543c037c1506dfe2e7a8db86bb6c1f2f94c7a
-  data.tar.gz: 716ed896e2f4960dcd3ca0afbd6ef94a43e45e63ea7f7284c1d277bfb2366418
+  metadata.gz: 1e3f2795566f0f5c947da5064603b1307f6dabac8d3e3821091db761cf16b12e
+  data.tar.gz: 4866374dafdfcaa976922b77e62e2d73640ee5b0a8c83b2c48ff0f44142df925
 SHA512:
-  metadata.gz: 371849705f4387e78f3c98d08982274ad072bf519f2699c6d1df7de5254fe70e01c1e3a8d2c3d54cd2fe1573666c9fc871431726089a5907c586f6dbdfe0a7c0
-  data.tar.gz: 8e408633d2862da41b4e546ad717153a8312e7983698058aeb53da5435523fff670ee1fe4ed2d9cb392b9aed7f655737046122aa9e2e09efe3455eea9f63d941
+  metadata.gz: 2e16f7692d02822b00b5726935ae7f915bc59db28e79562ae7cc023284ca0d3369683244ddaa26045a7207e07e8e27f80796e06daa69dc1963bc0522d46cec7e
+  data.tar.gz: 1d6e9af3f6fe60bdd2b461eaaf01dc5f3d4980ede10a3498994691dbe23c38e01c6ab49b41eff65ac637e5bf05bb2342a20675ce00b366dc7979cb224845f188

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.2.2
+
+### Fixed
+
+- CI workflow now matches the documented release matrix for Ruby `3.1`, `3.2`, `3.3`, `3.4`, `4.0` crossed with `jwt ~> 3.1.0` and `jwt ~> 3.2.0`.
+- Renamed the synthetic RFC 9964 regression test file to `test_ml_dsa_sizes.rb`; it now describes size and canonical-thumbprint checks without implying full Appendix-vector coverage.
+- `JWT::JWK::AKP` no longer expands and retains private seed material during initialization; private key materialization is lazy and happens only when `#secret_key` / `#signing_key` is requested.
+- `JWKS.from_keys(kids:)` now raises `ArgumentError` when the number of kids does not match the number of public keys.
+- JWKS lookup now ignores structurally invalid AKP JWK entries instead of returning malformed keys from weak filters.
+- JWKS lookup now prefilters by `kid`/`alg` before reconstructing public keys and uses a bounded immutable validation cache for repeated lookups.
+- `JWKS.from_keys(kids:)` now normalizes Array-compatible `kids` objects through `to_ary` before indexing.
+- `JWK.thumbprint` now validates the AKP `pub` length for the declared ML-DSA algorithm before computing the digest.
+- `DetachedSigningInputIO` now implements `#readpartial`, `#binmode`, `#binmode?`, and `#close` for better IO compatibility.
+
+### Added
+
+- `PQCrypto::JWT::JWK.thumbprint_uri(jwk)` for RFC 9278-style JWK thumbprint URIs.
+- `PQCrypto::JWT::JWKS.from_keys(..., kid_strategy: :thumbprint)` and `kid_strategy: :thumbprint_uri` for automatic key IDs.
+- Optional `strict: true` mode for streaming detached JWS verification, raising `JWT::DecodeError` for structural/token errors and `JWT::VerificationError` for cryptographic verification failures.
+- Thread-safe cache invalidation for `JWKS.loader`.
+- Optional Node `jose` cross-implementation interop test for `ML-DSA-65`, wired as a dedicated CI job.
+
+## 0.2.1
+
+### Fixed
+
+- Streaming detached JWS signing now rejects protected `b64` and `crit` headers instead of allowing semantic mismatch with the base64url-encoded signing input.
+- Streaming detached JWS verification now fails closed for critical headers and `b64: false`.
+- Streaming `chunk_size` is now validated as a positive integer before signing, verification, or detached signing-input reads.
+
+### Added
+
+- Negative streaming tests for `crit`, `b64`, malformed base64url headers, and non-positive chunk sizes.
+- Regression tests for ML-DSA public key/signature sizes and AKP JWK thumbprint canonical members.
+- Explicit tests and documentation for trusted private AKP JWK import without `verify_public: true`.
+
 ## 0.2.0
 
 ### Changed
@@ -11,7 +47,7 @@
 - PEM/DER loading now delegates to `PQCrypto::Key.from_pem` / `PQCrypto::Key.from_der` for auto-dispatch instead of manually parsing ASN.1 OIDs in the JWT adapter.
 - `signature_length_valid?` now fails closed when signature metadata cannot be resolved.
 - `JWT::JWK.classes` is no longer mutated at require-time; AKP registration happens through `PQCrypto::JWT.register!`.
-- CI matrix now covers Ruby `3.1`, `3.2`, `3.3`, `3.4`, `4.0` crossed with `jwt ~> 3.1.0` and `jwt ~> 3.2.0`.
+- Documented the intended Ruby `3.1`, `3.2`, `3.3`, `3.4`, `4.0` and `jwt >= 3.1, < 4.0` compatibility target.
 
 ### Added
 

data/README.md

@@ -18,6 +18,8 @@ ML-KEM/JWE is **not included**. Full JWE support needs a separate standards-comp
 - `pq_crypto` `~> 0.6.1`
 - `jwt` `>= 3.1`, `< 4.0`
 
+The CI release matrix covers Ruby `3.1`, `3.2`, `3.3`, `3.4`, `4.0` crossed with `jwt ~> 3.1.0` and `jwt ~> 3.2.0` on Linux and macOS. A dedicated Node `jose` interop job runs on Node 24 with `JOSE_INTEROP=1`.
+
 `pq_crypto-jwt` is Ruby-only and does not ship its own native extension. Native ML-DSA work, seed-aware keys, PKCS#8/SPKI parsing, and streaming signing/verification are delegated to `pq_crypto`.
 
 ## Install
@@ -113,7 +115,7 @@ Private AKP JWK uses RFC 9964 seed format: `priv` is the 32 raw-byte ML-DSA seed
 secret_key = PQCrypto::JWT::JWK.secret_key_from_jwk(private_jwk)
 ```
 
-With `pq_crypto 0.6.1`, private import trusts the JWK `pub` field as metadata because the parent gem does not expose public seed derivation yet. Callers that need a strict `pub`/`priv` consistency check can request it explicitly; this will raise `UnsupportedFeature` until the parent exposes `Signature.public_key_from_seed` or `Signature.keypair_from_seed`:
+With `pq_crypto 0.6.1`, private import trusts the JWK `pub` field as metadata because the parent gem does not expose public seed derivation yet. `secret_key_from_jwk` without `verify_public: true` is suitable only for trusted private JWK material. It does not prove that `pub` belongs to `priv`. Callers that need a strict `pub`/`priv` consistency check can request it explicitly; this will raise `UnsupportedFeature` until the parent exposes `Signature.public_key_from_seed` or `Signature.keypair_from_seed`:
 
 ```ruby
 secret_key = PQCrypto::JWT::JWK.secret_key_from_jwk(private_jwk, verify_public: true)
@@ -129,6 +131,15 @@ jwk = PQCrypto::JWT::JWK.from_seed(seed_32_bytes, alg: "ML-DSA-65", public_key:
 
 `from_secret_key` is reserved for a future parent release that exposes a public seed accessor. Expanded-only keys, and current `pq_crypto 0.6.1` keys, raise `UnsupportedFeature` instead of reading parent private state.
 
+JWK thumbprints are available as raw RFC 7638 thumbprints or RFC 9278-style URIs:
+
+```ruby
+thumbprint = PQCrypto::JWT::JWK.thumbprint(jwk)
+thumbprint_uri = PQCrypto::JWT::JWK.thumbprint_uri(jwk)
+```
+
+`thumbprint` validates that `pub` has the expected ML-DSA public-key length for the declared `alg` before hashing the canonical AKP members.
+
 JWKS lookup with `ruby-jwt`:
 
 ```ruby
@@ -140,7 +151,14 @@ token = JWT.encode({ "sub" => "alice" }, keypair.secret_key, "ML-DSA-65", kid: "
 payload, header = JWT.decode(token, nil, true, algorithms: ["ML-DSA-65"], jwks: jwks)
 ```
 
-For rotation, pass `PQCrypto::JWT::JWKS.loader(callable_or_hash)` as the `jwks:` value. The loader refreshes when `ruby-jwt` calls it with `invalidate: true`.
+`JWKS.from_keys(kids:)` requires one `kid` per public key. For automatic key IDs, derive them from the AKP thumbprint:
+
+```ruby
+jwks = PQCrypto::JWT::JWKS.from_keys([keypair.public_key], kid_strategy: :thumbprint)
+jwks = PQCrypto::JWT::JWKS.from_keys([keypair.public_key], kid_strategy: :thumbprint_uri)
+```
+
+For rotation, pass `PQCrypto::JWT::JWKS.loader(callable_or_hash)` as the `jwks:` value. The loader is thread-safe and refreshes when `ruby-jwt` calls it with `invalidate: true`.
 
 ## Streaming detached JWS
 
@@ -173,6 +191,19 @@ PQCrypto::JWT::JWA::MLDSA87
 
 `verify_io` returns `[payload_position, header]` on success. `payload_position` is `nil` for non-seekable streams that do not respond to `#pos`.
 
+By default, streaming verification fails closed and returns `false` for malformed tokens or failed signatures. Use `strict: true` when callers need error classification: structural/token errors raise `JWT::DecodeError`, and cryptographic verification failures raise `JWT::VerificationError`.
+
+```ruby
+PQCrypto::JWT::JWA::MLDSA65.verify_io(
+  verification_key: keypair.public_key,
+  token: token,
+  payload_io: payload_io,
+  strict: true
+)
+```
+
+The streaming helper signs the regular compact JWS signing input with a base64url-encoded payload. It does not implement RFC 7797 unencoded payload mode. `sign_io` rejects protected `b64` and `crit` header fields, and `verify_io` fails closed for critical headers or `b64: false`. `chunk_size` must be a positive integer.
+
 ## Non-goals
 
 This adapter deliberately does **not** expose:
@@ -194,7 +225,7 @@ JWK seed encoding; backed by pq_crypto, which should also be reviewed before
 production use.
 ```
 
-Use in production only after your own security review and interoperability testing.
+Use in production only after your own security review and interoperability testing. The repository includes an optional Node `jose` interop test (`JOSE_INTEROP=1 bundle exec ruby test/test_jose_interop.rb`) for the ML-DSA-65 JWS/JWK path.
 
 ## License
 

data/lib/pq_crypto/jwt/jwa/ml_dsa_streaming.rb

@@ -8,7 +8,8 @@ module PQCrypto
     module JWA
       module MLDSAStreaming
         DEFAULT_CHUNK_SIZE = 1 << 20
-        STREAMING_ERRORS = [JSON::ParserError, ArgumentError, PQCrypto::Error, PQCrypto::JWT::Error, EncodingError].freeze
+        STREAMING_DECODE_ERRORS = [JSON::ParserError, ArgumentError, TypeError, EncodingError].freeze
+        STREAMING_VERIFY_ERRORS = [PQCrypto::Error, PQCrypto::JWT::Error].freeze
 
         def streaming_supported?
           PQCrypto::Signature.supported.include?(pq_crypto_algorithm)
@@ -19,10 +20,12 @@ module PQCrypto
         def sign_io(signing_key:, payload_io: nil, io: nil, header_fields: {}, chunk_size: DEFAULT_CHUNK_SIZE)
           ensure_streaming!
           ensure_key!(signing_key, PQCrypto::Signature::SecretKey, "signing")
+          validate_chunk_size!(chunk_size)
           source = payload_io || io
           raise ArgumentError, "payload_io must respond to #read" unless source.respond_to?(:read)
 
-          encoded_header = base64url(JSON.generate(header_fields.transform_keys(&:to_s).merge("alg" => alg)))
+          header = normalize_signing_header!(header_fields).merge("alg" => alg)
+          encoded_header = base64url(JSON.generate(header))
           input = DetachedSigningInputIO.new(encoded_header, source, chunk_size: chunk_size)
           signature = signing_key.sign_io(input, chunk_size: chunk_size, context: EMPTY_CONTEXT)
           "#{encoded_header}..#{base64url(signature)}"
@@ -32,27 +35,32 @@ module PQCrypto
           raise ::JWT::EncodeError, e.message
         end
 
-        def verify_io(verification_key:, token:, payload_io:, chunk_size: DEFAULT_CHUNK_SIZE)
+        def verify_io(verification_key:, token:, payload_io:, chunk_size: DEFAULT_CHUNK_SIZE, strict: false)
           ensure_streaming!
           ensure_key!(verification_key, PQCrypto::Signature::PublicKey, "verification")
-          raise ArgumentError, "token must be a String" unless token.is_a?(String)
-          raise ArgumentError, "payload_io must respond to #read" unless payload_io.respond_to?(:read)
+          validate_chunk_size!(chunk_size)
+          return streaming_decode_failure!(strict, "token must be a String") unless token.is_a?(String)
+          return streaming_decode_failure!(strict, "payload_io must respond to #read") unless payload_io.respond_to?(:read)
 
           encoded_header, encoded_payload, encoded_signature, extra = token.split(".", -1)
-          return false unless extra.nil? && encoded_payload == "" && encoded_signature
+          unless extra.nil? && encoded_payload == "" && encoded_signature
+            return streaming_decode_failure!(strict, "compact detached JWS must have exactly three segments and an empty payload segment")
+          end
 
           header = JSON.parse(Base64.urlsafe_decode64(encoded_header))
-          return false unless header.is_a?(Hash) && header["alg"] == alg
+          return streaming_decode_failure!(strict, "unsupported streaming JWS protected header") unless supported_streaming_header?(header)
 
           signature = Base64.urlsafe_decode64(encoded_signature)
-          return false unless signature_length_valid?(signature)
+          return streaming_verify_failure!(strict, "invalid #{alg} signature length") unless signature_length_valid?(signature)
 
           input = DetachedSigningInputIO.new(encoded_header, payload_io, chunk_size: chunk_size)
-          return false unless verification_key.verify_io(input, signature, chunk_size: chunk_size, context: EMPTY_CONTEXT)
+          return streaming_verify_failure!(strict, "Streaming JWS verification failed") unless verification_key.verify_io(input, signature, chunk_size: chunk_size, context: EMPTY_CONTEXT)
 
           [payload_io.respond_to?(:pos) ? payload_io.pos : nil, header]
-        rescue *STREAMING_ERRORS
-          false
+        rescue *STREAMING_DECODE_ERRORS => e
+          streaming_decode_failure!(strict, e.message)
+        rescue *STREAMING_VERIFY_ERRORS => e
+          streaming_verify_failure!(strict, e.message)
         end
 
         def verify_io!(**kwargs)
@@ -71,10 +79,54 @@ module PQCrypto
         def base64url(bytes)
           Base64.urlsafe_encode64(String(bytes).b, padding: false)
         end
+
+        def normalize_signing_header!(header_fields)
+          unless header_fields.respond_to?(:to_hash)
+            raise ArgumentError, "header_fields must be a Hash-like object"
+          end
+
+          header = header_fields.to_hash.each_with_object({}) { |(key, value), out| out[String(key)] = value }
+          unsupported = %w[b64 crit] & header.keys
+          unless unsupported.empty?
+            raise ArgumentError, "unsupported protected header#{unsupported.size == 1 ? '' : 's'}: #{unsupported.join(', ')}"
+          end
+
+          header
+        end
+
+        def supported_streaming_header?(header)
+          return false unless header.is_a?(Hash) && header["alg"] == alg
+          return false if header.key?("crit")
+          return false if header.key?("b64") && header["b64"] != true
+
+          true
+        end
+
+        def validate_chunk_size!(chunk_size)
+          return if chunk_size.is_a?(Integer) && chunk_size.positive?
+
+          raise ArgumentError, "chunk_size must be a positive Integer"
+        end
+
+        def streaming_decode_failure!(strict, message)
+          raise ::JWT::DecodeError, message if strict
+
+          false
+        end
+
+        def streaming_verify_failure!(strict, message)
+          raise ::JWT::VerificationError, message if strict
+
+          false
+        end
       end
 
       class DetachedSigningInputIO
         def initialize(encoded_header, payload_io, chunk_size: MLDSAStreaming::DEFAULT_CHUNK_SIZE)
+          unless chunk_size.is_a?(Integer) && chunk_size.positive?
+            raise ArgumentError, "chunk_size must be a positive Integer"
+          end
+
           @prefix = "#{encoded_header}.".b
           @payload_io = payload_io
           @chunk_size = chunk_size
@@ -105,6 +157,17 @@ module PQCrypto
           replace_outbuf(outbuf, result)
         end
 
+        def readpartial(maxlen, outbuf = nil)
+          result = read(maxlen, outbuf)
+          raise EOFError if result.nil? || result.empty?
+
+          result
+        end
+
+        def binmode = self
+        def binmode? = true
+        def close = nil
+
         private
 
         def replace_outbuf(outbuf, result)

data/lib/pq_crypto/jwt/jwk/akp.rb

@@ -19,7 +19,7 @@ module JWT
         params = params.is_a?(String) ? { kid: params } : (params || {})
         params = params.transform_keys(&:to_sym)
         key_params = extract_key_params(key)
-        @checked_public_key, @checked_secret_key = check_jwk_params!(key_params, params)
+        @checked_public_key = check_jwk_params!(key_params, params)
         super({ kid_generator: NullKidGenerator }.merge(options || {}), key_params.merge(params))
       end
 
@@ -35,7 +35,7 @@ module JWT
       def secret_key
         raise JWT::JWKError, "AKP JWK does not contain private material" unless private?
 
-        @secret_key ||= @checked_secret_key || PQCrypto::JWT::JWK.secret_key_from_jwk(string_export(include_private: true))
+        @secret_key ||= PQCrypto::JWT::JWK.secret_key_from_jwk(string_export(include_private: true))
       end
 
       def export(options = {})
@@ -80,6 +80,14 @@ module JWT
         raise JWT::JWKError, e.message
       end
 
+      def validate_private_seed_metadata!(jwk)
+        seed = PQCrypto::JWT::JWK.base64url_decode(jwk.fetch("priv") { raise PQCrypto::JWT::Error, "JWK priv is required" })
+        return if seed.bytesize == PQCrypto::JWT::JWK::SEED_BYTES
+
+        raise PQCrypto::JWT::Error,
+              "Invalid priv seed length for #{jwk.fetch('alg').inspect}: expected #{PQCrypto::JWT::JWK::SEED_BYTES}, got #{seed.bytesize}"
+      end
+
       def check_jwk_params!(key_params, params)
         raise ArgumentError, "cannot overwrite cryptographic key attributes" unless (AKP_KEY_ELEMENTS & params.keys).empty?
         raise JWT::JWKError, "Incorrect 'kty' value: #{key_params[:kty]}, expected #{KTY}" unless key_params[:kty] == KTY
@@ -88,10 +96,8 @@ module JWT
         raise JWT::JWKError, "Unsupported AKP JWK alg: #{key_params[:alg].inspect}" unless PQCrypto::JWT.algorithm_for(key_params[:alg])
 
         parsed = key_params.transform_keys(&:to_s)
-        [
-          PQCrypto::JWT::JWK.public_key_from_jwk(parsed),
-          key_params[:priv] ? PQCrypto::JWT::JWK.secret_key_from_jwk(parsed) : nil
-        ]
+        validate_private_seed_metadata!(parsed) if key_params.key?(:priv)
+        PQCrypto::JWT::JWK.public_key_from_jwk(parsed)
       rescue PQCrypto::JWT::Error => e
         raise JWT::JWKError, e.message
       end

data/lib/pq_crypto/jwt/jwk.rb

@@ -11,6 +11,7 @@ module PQCrypto
 
       KTY = "AKP".freeze
       SEED_BYTES = defined?(PQCrypto::PKCS8::ML_DSA_SEED_BYTES) ? PQCrypto::PKCS8::ML_DSA_SEED_BYTES : 32
+      THUMBPRINT_URI_PREFIX = "urn:ietf:params:oauth:jwk-thumbprint:sha-256:".freeze
 
       def from_public_key(public_key, kid: nil, use: nil, key_ops: nil)
         validate_key!(public_key, PQCrypto::Signature::PublicKey)
@@ -72,13 +73,17 @@ module PQCrypto
 
       def thumbprint(jwk_hash)
         jwk = normalize_hash!(jwk_hash)
-        algorithm_from_jwk!(jwk)
-        raise PQCrypto::JWT::Error, "JWK pub is required" unless jwk.key?("pub")
+        algorithm = algorithm_from_jwk!(jwk)
+        decode_field!(jwk, "pub", algorithm)
 
         canonical = JSON.generate("alg" => jwk.fetch("alg"), "kty" => KTY, "pub" => jwk.fetch("pub"))
         base64url(Digest::SHA256.digest(canonical.b))
       end
 
+      def thumbprint_uri(jwk_hash)
+        "#{THUMBPRINT_URI_PREFIX}#{thumbprint(jwk_hash)}"
+      end
+
       def base64url(bytes)
         Base64.urlsafe_encode64(String(bytes).b, padding: false)
       end

data/lib/pq_crypto/jwt/jwks.rb

@@ -6,50 +6,166 @@ module PQCrypto
       module_function
 
       CACHE_EMPTY = Object.new.freeze
+      KID_STRATEGIES = %i[thumbprint thumbprint_uri].freeze
+      VALIDATION_CACHE_LIMIT = 1024
+      VALIDATION_CACHE_FIELD_BYTES_LIMIT = 8192
+      VALIDATION_CACHE = {}
+      VALIDATION_CACHE_MUTEX = Mutex.new
+      private_constant :VALIDATION_CACHE_FIELD_BYTES_LIMIT, :VALIDATION_CACHE, :VALIDATION_CACHE_MUTEX
 
-      def from_keys(public_keys, kids: nil)
-        keys = Array(public_keys).each_with_index.map do |public_key, index|
-          PQCrypto::JWT::JWK.from_public_key(public_key, kid: kids&.fetch(index, nil))
+      def from_keys(public_keys, kids: nil, kid_strategy: nil)
+        keys = Array(public_keys)
+        kids = normalize_kids!(keys, kids, kid_strategy)
+
+        jwks = keys.each_with_index.map do |public_key, index|
+          jwk = PQCrypto::JWT::JWK.from_public_key(public_key, kid: kids&.fetch(index))
+          apply_kid_strategy(jwk, kid_strategy)
         end
-        { "keys" => keys }.freeze
+        { "keys" => jwks }.freeze
       end
 
       def find(jwks, kid: nil, alg: nil, thumbprint: nil)
-        keys_from(jwks).find { |key| match?(key, kid, alg, thumbprint) }
+        each_candidate(jwks, kid, alg, thumbprint) do |key|
+          return key
+        end
+        nil
       end
 
       def find_all(jwks, kid: nil, alg: nil, thumbprint: nil)
-        keys_from(jwks).select { |key| match?(key, kid, alg, thumbprint) }
+        matches = []
+        each_candidate(jwks, kid, alg, thumbprint) { |key| matches << key }
+        matches
       end
 
       def loader(jwks_hash_or_callable)
         cached = CACHE_EMPTY
+        mutex = Mutex.new
+
         lambda do |options = {}|
           options ||= {}
-          cached = CACHE_EMPTY if options[:invalidate]
-          if cached.equal?(CACHE_EMPTY)
-            cached = jwks_hash_or_callable.respond_to?(:call) ? jwks_hash_or_callable.call(options) : jwks_hash_or_callable
+          invalidate = options[:invalidate]
+          current = cached
+          return current if !invalidate && !current.equal?(CACHE_EMPTY)
+
+          mutex.synchronize do
+            cached = CACHE_EMPTY if invalidate
+            if cached.equal?(CACHE_EMPTY)
+              cached = jwks_hash_or_callable.respond_to?(:call) ? jwks_hash_or_callable.call(options) : jwks_hash_or_callable
+            end
+            cached
           end
-          cached
         end
       end
 
-      def keys_from(jwks)
+      def raw_keys_from(jwks)
         source = jwks.respond_to?(:to_hash) ? jwks.to_hash : jwks
         keys = source.respond_to?(:[]) ? (source["keys"] || source[:keys]) : nil
-        Array(keys).map { |key| key.to_hash.each_with_object({}) { |(k, v), out| out[String(k)] = v } }
+        Array(keys)
+      end
+      private_class_method :raw_keys_from
+
+      def each_candidate(jwks, kid, alg, thumbprint)
+        raw_keys_from(jwks).each do |key|
+          next unless key.respond_to?(:to_hash)
+
+          normalized = normalize_jwk_hash(key.to_hash)
+          next unless cheap_match?(normalized, kid, alg)
+          next unless cached_valid_public_jwk?(normalized)
+          next unless thumbprint.nil? || PQCrypto::JWT::JWK.thumbprint(normalized) == thumbprint
+
+          yield normalized
+        rescue PQCrypto::JWT::Error, ArgumentError, TypeError
+          next
+        end
       end
-      private_class_method :keys_from
+      private_class_method :each_candidate
+
+      def normalize_jwk_hash(hash)
+        hash.each_with_object({}) { |(key, value), out| out[String(key)] = value }
+      end
+      private_class_method :normalize_jwk_hash
 
       def value_for(hash, key) = hash[key] || hash[key.to_sym]
       private_class_method :value_for
 
-      def match?(key, kid, alg, thumbprint)
+      def cheap_match?(key, kid, alg)
         (kid.nil? || value_for(key, "kid") == kid) &&
-          (alg.nil? || value_for(key, "alg") == alg) &&
-          (thumbprint.nil? || PQCrypto::JWT::JWK.thumbprint(key) == thumbprint)
+          (alg.nil? || value_for(key, "alg") == alg)
+      end
+      private_class_method :cheap_match?
+
+      def normalize_kids!(public_keys, kids, kid_strategy)
+        raise ArgumentError, "kid_strategy must be one of #{KID_STRATEGIES.inspect}" if kid_strategy && !KID_STRATEGIES.include?(kid_strategy)
+        raise ArgumentError, "kids and kid_strategy are mutually exclusive" if kids && kid_strategy
+        return nil unless kids
+
+        unless kids.respond_to?(:to_ary)
+          raise ArgumentError, "kids must be an Array with one kid per public key"
+        end
+
+        normalized = kids.to_ary
+        unless normalized.is_a?(Array)
+          raise ArgumentError, "kids must be an Array with one kid per public key"
+        end
+        raise ArgumentError, "kids.size must match public_keys.size" unless normalized.size == public_keys.size
+
+        normalized
+      end
+      private_class_method :normalize_kids!
+
+      def apply_kid_strategy(jwk, kid_strategy)
+        return jwk unless kid_strategy
+
+        kid = case kid_strategy
+              when :thumbprint then PQCrypto::JWT::JWK.thumbprint(jwk)
+              when :thumbprint_uri then PQCrypto::JWT::JWK.thumbprint_uri(jwk)
+              end
+        jwk.merge("kid" => kid).freeze
+      end
+      private_class_method :apply_kid_strategy
+
+      def cached_valid_public_jwk?(key)
+        cache_key = validation_cache_key(key)
+        return valid_public_jwk?(key) unless cache_key
+
+        VALIDATION_CACHE_MUTEX.synchronize do
+          cached = VALIDATION_CACHE[cache_key]
+          return cached unless cached.nil?
+        end
+
+        result = valid_public_jwk?(key)
+        VALIDATION_CACHE_MUTEX.synchronize do
+          VALIDATION_CACHE.shift if VALIDATION_CACHE.size >= VALIDATION_CACHE_LIMIT
+          VALIDATION_CACHE[cache_key] = result
+        end
+        result
+      end
+      private_class_method :cached_valid_public_jwk?
+
+      def validation_cache_key(key)
+        kty = key["kty"]
+        alg = key["alg"]
+        pub = key["pub"]
+        return nil unless kty.is_a?(String) && alg.is_a?(String) && pub.is_a?(String)
+        return nil if kty.bytesize > VALIDATION_CACHE_FIELD_BYTES_LIMIT
+        return nil if alg.bytesize > VALIDATION_CACHE_FIELD_BYTES_LIMIT
+        return nil if pub.bytesize > VALIDATION_CACHE_FIELD_BYTES_LIMIT
+
+        [kty.dup.freeze, alg.dup.freeze, pub.dup.freeze].freeze
+      end
+      private_class_method :validation_cache_key
+
+      def valid_public_jwk?(key)
+        PQCrypto::JWT::JWK.public_key_from_jwk(key)
+        true
+      rescue PQCrypto::JWT::Error, ArgumentError, TypeError
+        false
+      end
+      private_class_method :valid_public_jwk?
+
+      def clear_validation_cache!
+        VALIDATION_CACHE_MUTEX.synchronize { VALIDATION_CACHE.clear }
       end
-      private_class_method :match?
     end
   end
 end

data/lib/pq_crypto/jwt/version.rb

@@ -2,6 +2,6 @@
 
 module PQCrypto
   module JWT
-    VERSION = "0.2.0"
+    VERSION = "0.2.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pq_crypto-jwt
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Roman Haydarov
@@ -100,7 +100,7 @@ licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/roman-haidarov/pq_crypto-jwt
-  changelog_uri: https://github.com/roman-haidarov/pq_crypto-jwt/blob/v0.2.0/CHANGELOG.md
+  changelog_uri: https://github.com/roman-haidarov/pq_crypto-jwt/blob/v0.2.2/CHANGELOG.md
   bug_tracker_uri: https://github.com/roman-haidarov/pq_crypto-jwt/issues
 post_install_message:
 rdoc_options: []