jwt-pq 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da4d3ef14af28991259ed249b3a2e57a809d30729dff75f3a0ca084279552386
-  data.tar.gz: 6e557b8db0f0c8720ce3fbcae02d489399ccd071e9d8f2785a8fbfad812da254
+  metadata.gz: c0c45ba386fb98df768124e32529f0e0d80f574ddf0a0132e57e87a3ce94ea7a
+  data.tar.gz: c6071071b4814e40c707179d575447b7d730a1a2a789ba1cee5bdf71929abb47
 SHA512:
-  metadata.gz: b59cfa192a9a540949d52700605915a6c5fb86bf9cb7c2a43ad043cdecbab790c6b30d3ee2d70de55d16ce196a98af9dfbaad0dd0a8f03ae2c6c335759c3f5aa
-  data.tar.gz: 770546c6daf1c6645bef2198a94da9a0a76285429df70039980f894e015ae07a2a469f6627748d568c767ce294653173711798a0c7e2b6394f159010eadbd988
+  metadata.gz: 96c10bfd04d93b946f634257b95427a64e39cf23d8a10f330b1b4bdc3d29e212d0a575ddb7486df7ab47d88bd8af73d21ac4ec2620507db9c5289e2bc5a2588b
+  data.tar.gz: 88bc0b05ade5ab27f3dfa8b56d7f8bf3d8bb566145468e452c7a570db5db0e57ddabcc9ad452d86a48206633368675b83cf7a28d832f54a157cc80e75559464a

data/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-04-22
+
+### Added
+
+- Ruby 4.0 officially supported (CI matrix now covers 3.2, 3.3, 3.4, and 4.0 on Linux and macOS) (#40)
+- YARD reference site: `docs.yml` workflow publishes the generated docs to GitHub Pages on every tag push, served at `docs.jwt-pq.marcelopazzo.com` (#41)
+
+### Changed
+
+- `JWT::PQ::JWKSet.import` (and `JWKSet.fetch`) now tolerates mixed JWKSes: members with unknown `kty` (e.g. RSA, EC, OKP) or unsupported `alg` within `kty: "AKP"` are silently skipped instead of aborting the whole set — enabling incremental PQ rollouts where a single `/.well-known/jwks.json` carries both classical and ML-DSA keys. Pass `strict: true` to restore the previous fail-fast behaviour. Recognized-but-malformed AKP members still raise `KeyError` (#39)
+
 ## [0.5.1] - 2026-04-22
 
 ### Changed
@@ -140,7 +151,8 @@ Throughput on Ruby 3.4.6, macOS x86_64, liboqs 0.15.0 (benchmark-ips, 2s warmup
   - Optional dependency on jwt-eddsa / ed25519
 - Error classes: `LiboqsError`, `KeyError`, `SignatureError`, `MissingDependencyError`
 
-[Unreleased]: https://github.com/marcelopazzo/jwt-pq/compare/v0.5.1...HEAD
+[Unreleased]: https://github.com/marcelopazzo/jwt-pq/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/marcelopazzo/jwt-pq/compare/v0.5.1...v0.6.0
 [0.5.1]: https://github.com/marcelopazzo/jwt-pq/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/marcelopazzo/jwt-pq/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/marcelopazzo/jwt-pq/compare/v0.3.0...v0.4.0

data/README.md

@@ -138,6 +138,29 @@ signing: `JWT.encode(payload, key, alg, { kid: key.jwk_thumbprint })`.
 `Key#jwk_thumbprint` memoizes the digest, so it's cheap to call
 repeatedly on the same key.
 
+#### Mixed classical + PQ JWKSes
+
+`JWKSet.import` (and `JWKSet.fetch`) tolerates JWKSes that mix this
+gem's `ML-DSA-{44,65,87}` keys with classical RSA/EC/EdDSA entries or
+future PQ algorithms — members with an unknown `kty` or an
+unsupported `alg` within `kty: "AKP"` are silently dropped. This is
+the realistic shape of an incremental PQ rollout, where an issuer
+publishes both classical and ML-DSA keys on the same
+`/.well-known/jwks.json`.
+
+Members that **do** have `kty: "AKP"` with a supported `alg` but are
+otherwise malformed (missing `pub`, invalid base64url, wrong key size,
+etc.) still raise `JWT::PQ::KeyError` — that is a real bug in the
+emitter, not an interop boundary.
+
+Pass `strict: true` to restore fail-fast behaviour on any unknown
+`kty`/`alg`:
+
+```ruby
+JWT::PQ::JWKSet.import(body, strict: true)
+JWT::PQ::JWKSet.fetch(url, strict: true)
+```
+
 ### Fetching a remote JWKS
 
 For consuming a JWKS from an identity provider or sibling service,

data/SECURITY.md

@@ -6,8 +6,8 @@ jwt-pq is pre-1.0. Only the latest minor release receives security fixes.
 
 | Version | Supported |
 |---------|-----------|
-| 0.5.x   | Yes       |
-| < 0.5   | No        |
+| 0.6.x   | Yes       |
+| < 0.6   | No        |
 
 ## Reporting a vulnerability
 

data/SPEC.md

@@ -4,9 +4,9 @@ This document records which external specifications each jwt-pq release
 targets, what its current divergences are (if any), and the compatibility
 policy for drafts in flight.
 
-## Tracked specifications — jwt-pq 0.5.x
+## Tracked specifications — jwt-pq 0.6.x
 
-Last reviewed: **2026-04-20**.
+Last reviewed: **2026-04-22**.
 
 | Spec                                                                                    | Role in jwt-pq                                                                                 | Status                      |
 |-----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|-----------------------------|

data/jwt-pq.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
     "source_code_uri" => github_uri,
     "changelog_uri" => "#{github_uri}/blob/main/CHANGELOG.md",
     "bug_tracker_uri" => "#{github_uri}/issues",
-    "documentation_uri" => "https://rubydoc.info/gems/jwt-pq",
+    "documentation_uri" => "https://docs.jwt-pq.marcelopazzo.com",
     "rubygems_mfa_required" => "true"
   }
 

data/lib/jwt/pq/jwk.rb

@@ -98,6 +98,27 @@ module JWT
         end
       end
 
+      # Whether a JWK hash looks like something this gem can import:
+      # a JSON object with `kty == "AKP"` and a supported ML-DSA `alg`.
+      #
+      # Used by {JWT::PQ::JWKSet.import} to tolerate mixed JWKSes during
+      # incremental PQ rollouts — a `/.well-known/jwks.json` carrying a
+      # blend of RSA/EdDSA and ML-DSA members will not raise on the
+      # classical entries. It does **not** validate the remaining fields
+      # (`pub`, `priv`, base64url-ness, key sizes); a recognized-but-
+      # malformed member still raises from {.import}, since that signals
+      # a real bug in the emitter rather than an interop boundary.
+      #
+      # @api private
+      # @param jwk_hash [Object] candidate JWK.
+      # @return [Boolean] true iff the member is in this gem's scope.
+      def self.recognized?(jwk_hash)
+        return false unless jwk_hash.is_a?(Hash)
+
+        jwk = normalize_keys(jwk_hash)
+        jwk["kty"] == KTY && ALGORITHMS.include?(jwk["alg"])
+      end
+
       # Compute the JWK Thumbprint (RFC 7638) used as `kid`.
       #
       # Delegates to {JWT::PQ::Key#jwk_thumbprint}, which memoizes the

data/lib/jwt/pq/jwk_set.rb

@@ -127,8 +127,20 @@ module JWT
 
       # Import a JWKS from a Hash or JSON string.
       #
-      # Each member is reconstructed via {JWT::PQ::JWK.import}; malformed
-      # members raise {KeyError}.
+      # By default, members this gem cannot represent — unknown `kty`
+      # (e.g. `RSA`, `EC`, `OKP`) or unknown `alg` within `kty: "AKP"`
+      # (e.g. a future ML-DSA parameter set or a sibling PQ algorithm not
+      # yet implemented here) — are silently dropped. This keeps the set
+      # usable during an incremental PQ rollout, where a single
+      # `/.well-known/jwks.json` carries both classical and ML-DSA keys.
+      #
+      # Members that **are** in scope (`kty: "AKP"` with a supported
+      # `alg`) but malformed — missing `pub`, wrong field type, invalid
+      # base64url, wrong key size — still raise {KeyError}: that is a
+      # real bug in the emitter, not an interop boundary.
+      #
+      # Pass `strict: true` to restore the previous fail-fast behaviour,
+      # where any unknown `kty`/`alg` raises.
       #
       # ML-DSA public keys are ~1.3–2.6 KB each, so a JWKS with N keys is
       # at least N × ~2 KB. When ingesting untrusted JWKS payloads (e.g.
@@ -138,10 +150,14 @@ module JWT
       #
       # @param source [Hash, String] a JWKS hash or JSON string with a
       #   `"keys"` array.
-      # @return [JWKSet] a new set with all parsed members.
+      # @param strict [Boolean] if true, unknown `kty`/`alg` members
+      #   raise {KeyError} instead of being skipped. Default: false.
+      # @return [JWKSet] a new set with the parsed in-scope members.
       # @raise [KeyError] if `source` is not a Hash/String, if the `keys`
-      #   field is missing or not an Array, or if any member fails to import.
-      def self.import(source)
+      #   field is missing or not an Array, if an in-scope member is
+      #   malformed, or (only when `strict: true`) if any member has an
+      #   unknown `kty`/`alg`.
+      def self.import(source, strict: false)
         hash = coerce_to_hash(source)
         raise KeyError, "Expected Hash for JWKS body, got #{hash.class}" unless hash.is_a?(Hash)
 
@@ -149,10 +165,18 @@ module JWT
         raise KeyError, "Missing 'keys' in JWKS" unless hash.key?("keys")
         raise KeyError, "'keys' must be an Array" unless hash["keys"].is_a?(Array)
 
-        members = hash["keys"].map { |jwk| JWT::PQ::JWK.import(jwk) }
+        members = hash["keys"].filter_map { |jwk| import_member(jwk, strict: strict) }
         new(members)
       end
 
+      # @api private
+      def self.import_member(jwk, strict:)
+        return nil unless strict || JWT::PQ::JWK.recognized?(jwk)
+
+        JWT::PQ::JWK.import(jwk)
+      end
+      private_class_method :import_member
+
       # @api private
       def self.coerce_to_hash(source)
         case source
@@ -184,6 +208,10 @@ module JWT
       #   key = jwks[header["kid"]] or raise "unknown kid"
       #   payload, = JWT.decode(token, key, true, algorithms: [header["alg"]])
       #
+      # By default, members with unknown `kty`/`alg` in the fetched
+      # body are skipped (see {.import}); pass `strict: true` to make
+      # them raise.
+      #
       # @param url [String] absolute JWKS URL.
       # @return [JWKSet] the parsed set of verification keys.
       # @raise [JWKSFetchError] on fetch failure (see {Loader#fetch}).

data/lib/jwt/pq/jwks_loader.rb

@@ -80,6 +80,9 @@ module JWT
         #   Default: 1 MB.
         # @param allow_http [Boolean] allow plain `http://` URLs. Default:
         #   false (strongly recommended for production).
+        # @param strict [Boolean] forwarded to {JWKSet.import}: if true,
+        #   members with unknown `kty`/`alg` raise instead of being
+        #   skipped. Default: false.
         # @return [JWKSet] the parsed set of verification keys.
         # @raise [JWKSFetchError] on network error, timeout, non-2xx
         #   response, oversized body, redirect, or non-HTTPS URL.
@@ -89,7 +92,8 @@ module JWT
                   timeout: DEFAULT_TIMEOUT,
                   open_timeout: DEFAULT_OPEN_TIMEOUT,
                   max_body_bytes: DEFAULT_MAX_BODY_BYTES,
-                  allow_http: false)
+                  allow_http: false,
+                  strict: false)
           uri = validate_uri!(url, allow_http: allow_http)
 
           fresh = fresh_entry(url, cache_ttl)
@@ -102,7 +106,7 @@ module JWT
             @mutex.synchronize { existing.fetched_at = now }
             existing.jwks
           else
-            jwks = JWKSet.import(result[:body])
+            jwks = JWKSet.import(result[:body], strict: strict)
             @mutex.synchronize do
               @cache[url] = CacheEntry.new(jwks, result[:etag], now)
             end

data/lib/jwt/pq/version.rb

@@ -3,6 +3,6 @@
 module JWT
   module PQ
     # Current gem version.
-    VERSION = "0.5.1"
+    VERSION = "0.6.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jwt-pq
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Marcelo Almeida
@@ -91,7 +91,7 @@ metadata:
   source_code_uri: https://github.com/marcelopazzo/jwt-pq
   changelog_uri: https://github.com/marcelopazzo/jwt-pq/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/marcelopazzo/jwt-pq/issues
-  documentation_uri: https://rubydoc.info/gems/jwt-pq
+  documentation_uri: https://docs.jwt-pq.marcelopazzo.com
   rubygems_mfa_required: 'true'
 post_install_message: |
   jwt-pq compiles liboqs from source during installation.