pq_crypto-jwt 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f383c2f1f0414e4817f80ea6865dc4c9d7acdb512d33e1d3e368b7091f84e9c
-  data.tar.gz: 00ed418f44277af5ec23ae1ffb4be8edf909cf40e6d974cafd072fd2fdbd0c4f
+  metadata.gz: ded8bedea5417580ef9a3199f47543c037c1506dfe2e7a8db86bb6c1f2f94c7a
+  data.tar.gz: 716ed896e2f4960dcd3ca0afbd6ef94a43e45e63ea7f7284c1d277bfb2366418
 SHA512:
-  metadata.gz: a1f3e7e7bea52901a570378619485d0d7981129534738e30972187d02c35aa7061bc644c5b6c91ef006a640c9d483993e2d2382447c3b2e8a7205a241b15e922
-  data.tar.gz: c3cc3d4ef8e8b6e73b25cc17bd700f2acfe32b66114cca0b73ee983647856b794824bced8727360769577bbd83e3cc458ce374c2ab00de7886155cbbca46221f
+  metadata.gz: 371849705f4387e78f3c98d08982274ad072bf519f2699c6d1df7de5254fe70e01c1e3a8d2c3d54cd2fe1573666c9fc871431726089a5907c586f6dbdfe0a7c0
+  data.tar.gz: 8e408633d2862da41b4e546ad717153a8312e7983698058aeb53da5435523fff670ee1fe4ed2d9cb392b9aed7f655737046122aa9e2e09efe3455eea9f63d941

data/CHANGELOG.md

@@ -1,5 +1,61 @@
 # Changelog
 
+## 0.2.0
+
+### Changed
+
+- Retargeted the adapter to the current parent line: `pq_crypto ~> 0.6.1`.
+- Updated documentation and release language from draft-era ML-DSA JOSE wording to RFC 9964 terminology.
+- Explicitly pass the RFC 9964 empty ML-DSA context in all one-shot and streaming sign/verify paths.
+- Streaming detached JWS now applies to `ML-DSA-44`, `ML-DSA-65`, and `ML-DSA-87` instead of only `ML-DSA-65`.
+- 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`.
+
+### Added
+
+- `PQCrypto::JWT::UnsupportedFeature` for release-scope or parent-API-gated functionality.
+- Seed-based private AKP JWK import via `PQCrypto::JWT::JWK.secret_key_from_jwk`.
+- Optional strict private JWK `pub`/`priv` consistency verification via `verify_public: true` for both import and explicit seed export; this is gated on future parent public seed-derivation APIs.
+- Explicit seed-based private AKP JWK export via `PQCrypto::JWT::JWK.from_seed(..., public_key:)`, with optional `verify_public: true` consistency checking when parent support exists.
+- Reserved `PQCrypto::JWT::JWK.from_secret_key` for future seed-exporting parent keys; current `pq_crypto 0.6.1` keys raise `UnsupportedFeature` instead of reading private parent state.
+- Optional public JWK metadata on export: `use:` and `key_ops:`.
+- DER helper methods:
+  - `PQCrypto::JWT::Keys.public_from_der`
+  - `PQCrypto::JWT::Keys.secret_from_der`
+- JWKS lookup helpers for JWK thumbprint fallback and multi-match rotation windows:
+  - `PQCrypto::JWT::JWKS.find(..., thumbprint:)`
+  - `PQCrypto::JWT::JWKS.find_all`
+- Negative tests for malformed streaming headers, extra compact segments, invalid private seed lengths, strict private JWK verification gating, dependency constraints, private API constraints, and read contract behavior.
+
+### Fixed
+
+- Removed private parent-state reads from private AKP JWK export; the adapter no longer uses parent instance variables as compatibility API.
+- `DetachedSigningInputIO#read(nil)` now follows the Ruby IO contract and reads to EOF.
+- Streaming verification now rejects non-object decoded JOSE headers before consulting `alg`.
+- Streaming verification now rejects compact tokens with extra segments.
+- One-shot verification rescues only expected verification/input/encoding errors instead of masking all `StandardError`.
+- `JWT::JWK::AKP` no longer advertises automatic dispatch for `SecretKey`/`Keypair` until parent seed-export APIs exist.
+- Removed a redundant unreachable private-JWK parameter check from `JWT::JWK::AKP`.
+- JWKS loader caching no longer relies on `||=`, so falsey JWKS values do not cause repeated reloads.
+
+### Deferred
+
+- Composite / hybrid JOSE signatures.
+- ML-KEM / JWE support.
+- RBS / Sorbet signatures.
+- Macro refactor for the three ML-DSA modules.
+
+## 0.1.2
+
+### Changed
+
+- Lowered the supported Ruby floor from `>= 3.4.0` to `>= 3.1.0`, matching the `pq_crypto` 0.5.x compatibility line.
+- Updated the runtime dependency to `pq_crypto >= 0.5.3, < 0.6` so Ruby 3.1-3.3 use the compatibility path from the core gem while Ruby 3.4+ keeps the optimized path.
+- Expanded CI coverage to Ruby 3.1, 3.2, 3.3, 3.4, and 4.0 on Linux and macOS.
+- Added hard-constraint tests for the Ruby floor and `pq_crypto` dependency range.
+
 ## Initial public release
 
 ### Included

data/README.md

@@ -2,19 +2,28 @@
 
 `pq_crypto-jwt` is a small adapter that connects [`pq_crypto`](https://rubygems.org/gems/pq_crypto) to the [`ruby-jwt`](https://rubygems.org/gems/jwt) ecosystem.
 
-The first public release intentionally focuses on one stable surface:
+This release focuses on the RFC 9964 ML-DSA JWS surface:
 
 - ML-DSA JWS signing and verification for `ruby-jwt`
-- public AKP JWK/JWKS helpers for ML-DSA verification keys
-- PEM import helpers for ML-DSA SPKI/PKCS#8 keys
-- ML-DSA-65 streaming detached JWS helper
+- AKP JWK/JWKS helpers for ML-DSA verification keys
+- seed-based private AKP JWK import and explicit seed export paths
+- PEM/DER import helpers for ML-DSA SPKI/PKCS#8 keys through `PQCrypto::Key`
+- streaming detached JWS helpers for `ML-DSA-44`, `ML-DSA-65`, and `ML-DSA-87`
 
-ML-KEM/JWE is **not included** in this first release. Full JWE support needs a separate standards-compatible implementation and interoperability tests.
+ML-KEM/JWE is **not included**. Full JWE support needs a separate standards-compatible implementation and interoperability tests.
+
+## Requirements
+
+- Ruby `>= 3.1.0`
+- `pq_crypto` `~> 0.6.1`
+- `jwt` `>= 3.1`, `< 4.0`
+
+`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
 
 ```ruby
-gem "pq_crypto-jwt", "~> 0.1"
+gem "pq_crypto-jwt", "~> 0.2"
 ```
 
 ## Register the algorithms
@@ -47,9 +56,11 @@ token = JWT.encode({ "sub" => "alice" }, keypair.secret_key, "ML-DSA-65")
 payload, header = JWT.decode(token, keypair.public_key, true, algorithm: "ML-DSA-65")
 ```
 
-The adapter validates both the JOSE algorithm string and the concrete pq_crypto key type. A token signed with `ML-DSA-44`, for example, will not verify under `ML-DSA-65`.
+The adapter validates both the JOSE algorithm string and the concrete `pq_crypto` key type. A token signed with `ML-DSA-44`, for example, will not verify under `ML-DSA-65`.
+
+For RFC 9964 JOSE algorithms, the FIPS 204 `ctx` value is fixed to the empty string. The adapter passes `context: "".b` explicitly in both one-shot and streaming paths and does not expose a per-token context option for `ML-DSA-44`, `ML-DSA-65`, or `ML-DSA-87`.
 
-## PEM import
+## PEM and DER import
 
 SPKI public keys and PKCS#8 secret keys can be imported through the helper API:
 
@@ -68,6 +79,13 @@ public_key = PQCrypto::JWT::Keys.public_from_pem(spki_pem, expect: :signature)
 secret_key = PQCrypto::JWT::Keys.secret_from_pem(pkcs8_pem, expect: :signature)
 ```
 
+DER helpers are also available:
+
+```ruby
+public_key = PQCrypto::JWT::Keys.public_from_der(spki_der)
+secret_key = PQCrypto::JWT::Keys.secret_from_der(pkcs8_der, passphrase: passphrase)
+```
+
 ## JWK and JWKS
 
 Public AKP JWK round-trip:
@@ -78,6 +96,39 @@ jwk = PQCrypto::JWT::JWK.from_public_key(keypair.public_key, kid: "signing-key")
 public_key = PQCrypto::JWT::JWK.public_key_from_jwk(jwk)
 ```
 
+Optional public JWK metadata can be supplied directly:
+
+```ruby
+jwk = PQCrypto::JWT::JWK.from_public_key(
+  keypair.public_key,
+  kid: "signing-key",
+  use: "sig",
+  key_ops: ["verify"]
+)
+```
+
+Private AKP JWK uses RFC 9964 seed format: `priv` is the 32 raw-byte ML-DSA seed encoded as base64url. It is not the expanded ML-DSA secret key, and helper APIs expect raw seed bytes, not hex or text encodings.
+
+```ruby
+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`:
+
+```ruby
+secret_key = PQCrypto::JWT::JWK.secret_key_from_jwk(private_jwk, verify_public: true)
+```
+
+Export is intentionally explicit. Current `pq_crypto 0.6.1` can import seed-aware keys but does not expose a stable public seed accessor / public-key-from-seed API, so use `from_seed` and pass the matching public key:
+
+```ruby
+jwk = PQCrypto::JWT::JWK.from_seed(seed_32_bytes, alg: "ML-DSA-65", public_key: public_key)
+```
+
+`from_seed` also accepts `verify_public: true` for symmetry with private import. On current `pq_crypto 0.6.1` this raises `UnsupportedFeature`; once the parent exposes public seed derivation, it will reject a `public_key:` that does not match the supplied seed. Without `verify_public: true`, the explicitly supplied `public_key:` is trusted.
+
+`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.
+
 JWKS lookup with `ruby-jwt`:
 
 ```ruby
@@ -89,11 +140,11 @@ 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.
+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`.
 
 ## Streaming detached JWS
 
-`ML-DSA-65` also supports a streaming detached JWS helper. The compact form is `header..signature`; callers must supply the same payload stream separately for verification.
+All three ML-DSA JOSE algorithms support the streaming detached JWS helper when backed by `pq_crypto ~> 0.6.1`. The compact form is `header..signature`; callers must supply the same payload stream separately for verification.
 
 ```ruby
 File.open("payload.bin", "rb") do |payload_io|
@@ -112,24 +163,35 @@ File.open("payload.bin", "rb") do |payload_io|
 end
 ```
 
-## Non-goals for the first release
+Equivalent helpers exist on:
+
+```text
+PQCrypto::JWT::JWA::MLDSA44
+PQCrypto::JWT::JWA::MLDSA65
+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`.
+
+## Non-goals
 
-The first release deliberately does **not** expose:
+This adapter deliberately does **not** expose:
 
 - ML-KEM JWE key agreement
 - JWE compact or JSON serialization
 - JWE content encryption, AAD, IV, or authentication tag handling
-- private AKP JWK import/export; use PEM/PKCS#8 for signing keys
+- composite / hybrid JOSE signatures
+- custom ML-DSA JOSE `ctx` values
 - general-purpose JWT claims policy beyond what `ruby-jwt` already provides
 
-This keeps the public API small and avoids publishing draft-incompatible JWE behavior.
+This keeps the public API small and avoids publishing speculative JWE or composite-signature behavior before the relevant JOSE work is stable.
 
 ## Security status
 
 ```text
-unaudited; tracks draft-ietf-cose-dilithium for ML-DSA JOSE identifiers;
-identifiers and wire formats may change before RFC publication; backed by
-pq_crypto, which should also be reviewed before production use.
+unaudited; implements the RFC 9964 ML-DSA JOSE algorithm identifiers and AKP
+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.

data/lib/pq_crypto/jwt/errors.rb

@@ -4,6 +4,7 @@ module PQCrypto
   module JWT
     class Error < StandardError; end
     class UnsupportedAlgorithm < Error; end
+    class UnsupportedFeature < Error; end
     class KeyTypeError < Error; end
   end
 end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../jwa"
+require_relative "ml_dsa_streaming"
 
 module PQCrypto
   module JWT
@@ -8,6 +9,7 @@ module PQCrypto
       module MLDSA44
         extend ::JWT::JWA::SigningAlgorithm
         extend PQCrypto::JWT::JWA::MLDSA
+        extend PQCrypto::JWT::JWA::MLDSAStreaming
 
         ALG = "ML-DSA-44".freeze
         PQ_CRYPTO_ALGORITHM = :ml_dsa_44

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "../jwa"
+require_relative "ml_dsa_streaming"
 
 module PQCrypto
   module JWT
@@ -8,6 +9,7 @@ module PQCrypto
       module MLDSA87
         extend ::JWT::JWA::SigningAlgorithm
         extend PQCrypto::JWT::JWA::MLDSA
+        extend PQCrypto::JWT::JWA::MLDSAStreaming
 
         ALG = "ML-DSA-87".freeze
         PQ_CRYPTO_ALGORITHM = :ml_dsa_87

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

@@ -8,24 +8,23 @@ module PQCrypto
     module JWA
       module MLDSAStreaming
         DEFAULT_CHUNK_SIZE = 1 << 20
-        EMPTY_CONTEXT = "".b.freeze
+        STREAMING_ERRORS = [JSON::ParserError, ArgumentError, PQCrypto::Error, PQCrypto::JWT::Error, EncodingError].freeze
 
         def streaming_supported?
-          pq_crypto_algorithm == :ml_dsa_65 &&
-            PQCrypto::Signature.supported.include?(:ml_dsa_65)
+          PQCrypto::Signature.supported.include?(pq_crypto_algorithm)
+        rescue PQCrypto::Error
+          false
         end
 
         def sign_io(signing_key:, payload_io: nil, io: nil, header_fields: {}, chunk_size: DEFAULT_CHUNK_SIZE)
-          raise PQCrypto::JWT::UnsupportedAlgorithm, "#{alg} does not support streaming JWS" unless streaming_supported?
-
-          ensure_secret_key!(signing_key)
+          ensure_streaming!
+          ensure_key!(signing_key, PQCrypto::Signature::SecretKey, "signing")
           source = payload_io || io
           raise ArgumentError, "payload_io must respond to #read" unless source.respond_to?(:read)
 
-          header = stringify_keys(header_fields || {}).merge("alg" => alg)
-          encoded_header = base64url(JSON.generate(header))
-          signing_input = DetachedSigningInputIO.new(encoded_header, source, chunk_size: chunk_size)
-          signature = signing_key.sign_io(signing_input, chunk_size: chunk_size, context: EMPTY_CONTEXT)
+          encoded_header = base64url(JSON.generate(header_fields.transform_keys(&:to_s).merge("alg" => alg)))
+          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)}"
         rescue PQCrypto::JWT::Error, ArgumentError
           raise
@@ -34,46 +33,43 @@ module PQCrypto
         end
 
         def verify_io(verification_key:, token:, payload_io:, chunk_size: DEFAULT_CHUNK_SIZE)
-          raise PQCrypto::JWT::UnsupportedAlgorithm, "#{alg} does not support streaming JWS" unless streaming_supported?
-          ensure_public_key!(verification_key)
+          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)
 
-          encoded_header, encoded_payload, encoded_signature = token.split(".", -1)
-          return false unless encoded_header && encoded_payload == "" && encoded_signature
+          encoded_header, encoded_payload, encoded_signature, extra = token.split(".", -1)
+          return false unless extra.nil? && encoded_payload == "" && encoded_signature
 
           header = JSON.parse(Base64.urlsafe_decode64(encoded_header))
-          return false unless header["alg"] == alg
+          return false unless header.is_a?(Hash) && header["alg"] == alg
 
           signature = Base64.urlsafe_decode64(encoded_signature)
-          signing_input = DetachedSigningInputIO.new(encoded_header, payload_io, chunk_size: chunk_size)
-          verified = verification_key.verify_io(signing_input, signature, chunk_size: chunk_size, context: EMPTY_CONTEXT)
-          return false unless verified
+          return false unless signature_length_valid?(signature)
 
-          [payload_position(payload_io), header]
-        rescue JSON::ParserError, ArgumentError, PQCrypto::InvalidKeyError
+          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)
+
+          [payload_io.respond_to?(:pos) ? payload_io.pos : nil, header]
+        rescue *STREAMING_ERRORS
           false
         end
 
-        def verify_io!(verification_key:, token:, payload_io:, chunk_size: DEFAULT_CHUNK_SIZE)
-          result = verify_io(verification_key: verification_key, token: token, payload_io: payload_io, chunk_size: chunk_size)
-          raise ::JWT::VerificationError, "Streaming JWS verification failed" unless result
-
+        def verify_io!(**kwargs)
+          verify_io(**kwargs) || raise(::JWT::VerificationError, "Streaming JWS verification failed")
           true
         end
 
         private
 
-        def base64url(bytes)
-          Base64.urlsafe_encode64(String(bytes).b, padding: false)
-        end
+        def ensure_streaming!
+          return if streaming_supported?
 
-        def stringify_keys(hash)
-          hash.each_with_object({}) { |(key, value), out| out[String(key)] = value }
+          raise PQCrypto::JWT::UnsupportedFeature, "#{alg} does not support streaming JWS"
         end
 
-        def payload_position(payload_io)
-          payload_io.respond_to?(:pos) ? payload_io.pos : nil
+        def base64url(bytes)
+          Base64.urlsafe_encode64(String(bytes).b, padding: false)
         end
       end
 
@@ -89,45 +85,67 @@ module PQCrypto
         end
 
         def read(length = nil, outbuf = nil)
-          length ||= @chunk_size
-          fill(length)
-          return nil if @buffer.empty?
+          if length.nil?
+            drain_until_eof
+            return nil if @buffer.empty?
+
+            result = @buffer
+            @buffer = +""
+          else
+            raise ArgumentError, "negative length #{length} given" if length.negative?
+            return replace_outbuf(outbuf, +"") if length.zero?
+
+            fill(length)
+            return nil if @buffer.empty?
+
+            result = @buffer.byteslice(0, length)
+            @buffer = @buffer.byteslice(result.bytesize..-1) || +""
+          end
 
-          result = @buffer.byteslice(0, length)
-          @buffer = @buffer.byteslice(result.bytesize..-1) || +""
+          replace_outbuf(outbuf, result)
+        end
+
+        private
+
+        def replace_outbuf(outbuf, result)
           outbuf&.replace(result)
           outbuf || result
         end
 
-        private
+        def drain_until_eof
+          consume_prefix
+          feed_one_chunk until @payload_done
+        end
 
         def fill(length)
-          @buffer << @prefix unless consume_prefix?
-          while @buffer.bytesize < length && !@payload_done
-            chunk = @payload_io.read(@chunk_size)
-            if chunk.nil? || chunk.empty?
-              @buffer << Base64.urlsafe_encode64(@carry, padding: false) unless @carry.empty?
-              @carry = +""
-              @payload_done = true
-              break
-            end
-
-            bytes = @carry + chunk.b
-            full_length = bytes.bytesize - (bytes.bytesize % 3)
-            if full_length.positive?
-              @buffer << Base64.urlsafe_encode64(bytes.byteslice(0, full_length), padding: false)
-              @carry = bytes.byteslice(full_length..-1) || +""
-            else
-              @carry = bytes
-            end
-          end
+          consume_prefix
+          feed_one_chunk while @buffer.bytesize < length && !@payload_done
         end
 
-        def consume_prefix?
-          return true if @prefix_done
+        def consume_prefix
+          return if @prefix_done
 
+          @buffer << @prefix
           @prefix_done = true
-          false
+        end
+
+        def feed_one_chunk
+          chunk = @payload_io.read(@chunk_size)
+          if chunk.nil? || chunk.empty?
+            @buffer << Base64.urlsafe_encode64(@carry, padding: false) unless @carry.empty?
+            @carry = +""
+            @payload_done = true
+            return
+          end
+
+          bytes = @carry + chunk.b
+          aligned = bytes.bytesize - (bytes.bytesize % 3)
+          if aligned.positive?
+            @buffer << Base64.urlsafe_encode64(bytes.byteslice(0, aligned), padding: false)
+            @carry = bytes.byteslice(aligned..-1) || +""
+          else
+            @carry = bytes
+          end
         end
       end
     end

data/lib/pq_crypto/jwt/jwa.rb

@@ -6,40 +6,23 @@ require "pq_crypto"
 module PQCrypto
   module JWT
     module JWA
-      module MLDSA
-        def valid_alg?(alg_to_validate)
-          alg_to_validate == alg
-        end
-
-        def pq_crypto_algorithm
-          self::PQ_CRYPTO_ALGORITHM
-        end
-
-        def streaming_supported?
-          false
-        end
-
-        def sign_io(**)
-          raise PQCrypto::JWT::UnsupportedAlgorithm, "#{alg} does not support streaming JWS"
-        end
-
-        def verify_io(**)
-          raise PQCrypto::JWT::UnsupportedAlgorithm, "#{alg} does not support streaming JWS"
-        end
+      EMPTY_CONTEXT = "".b.freeze
+      VERIFY_ERRORS = [
+        PQCrypto::Error, PQCrypto::JWT::Error,
+        ::JWT::DecodeError, ::JWT::VerificationError, ::JWT::JWKError,
+        ArgumentError, TypeError, EncodingError
+      ].freeze
 
-        def verify_io!(**)
-          raise PQCrypto::JWT::UnsupportedAlgorithm, "#{alg} does not support streaming JWS"
-        end
-
-        def key_kind
-          :signature
-        end
+      module MLDSA
+        def valid_alg?(alg_to_validate) = alg_to_validate == alg
+        def pq_crypto_algorithm = self::PQ_CRYPTO_ALGORITHM
+        def key_kind = :signature
 
         def sign(data:, signing_key:)
-          ensure_secret_key!(signing_key)
+          ensure_key!(signing_key, PQCrypto::Signature::SecretKey, "signing")
           raise ArgumentError, "data must be a String" unless data.is_a?(String)
 
-          signing_key.sign(data.b)
+          signing_key.sign(data.b, context: EMPTY_CONTEXT)
         rescue PQCrypto::JWT::KeyTypeError, ArgumentError
           raise
         rescue StandardError => e
@@ -47,47 +30,33 @@ module PQCrypto
         end
 
         def verify(data:, signature:, verification_key:)
-          return false unless public_key_for_this_algorithm?(verification_key)
-          return false unless data.is_a?(String)
-          return false unless signature.is_a?(String)
+          return false unless verification_key.is_a?(PQCrypto::Signature::PublicKey)
+          return false unless verification_key.algorithm == pq_crypto_algorithm
+          return false unless data.is_a?(String) && signature.is_a?(String)
           return false unless signature_length_valid?(signature)
 
-          verification_key.verify(data.b, signature.b)
-        rescue PQCrypto::InvalidKeyError, PQCrypto::JWT::Error, ArgumentError
+          verification_key.verify(data.b, signature.b, context: EMPTY_CONTEXT)
+        rescue *VERIFY_ERRORS
           false
         end
 
         private
 
-        def ensure_secret_key!(key)
-          unless key.is_a?(PQCrypto::Signature::SecretKey)
-            raise PQCrypto::JWT::KeyTypeError,
-                  "#{alg} signing requires PQCrypto::Signature::SecretKey"
+        def ensure_key!(key, klass, role)
+          unless key.is_a?(klass)
+            raise PQCrypto::JWT::KeyTypeError, "#{alg} #{role} requires #{klass}"
           end
-
           return if key.algorithm == pq_crypto_algorithm
 
           raise PQCrypto::JWT::KeyTypeError,
-                "#{alg} signing requires #{pq_crypto_algorithm.inspect} key, got #{key.algorithm.inspect}"
-        end
-
-        def ensure_public_key!(key)
-          unless public_key_for_this_algorithm?(key)
-            raise PQCrypto::JWT::KeyTypeError,
-                  "#{alg} verification requires PQCrypto::Signature::PublicKey for #{pq_crypto_algorithm.inspect}"
-          end
-        end
-
-        def public_key_for_this_algorithm?(key)
-          key.is_a?(PQCrypto::Signature::PublicKey) && key.algorithm == pq_crypto_algorithm
+                "#{alg} #{role} requires #{pq_crypto_algorithm.inspect} key, got #{key.algorithm.inspect}"
         end
 
         def signature_length_valid?(signature)
-          details = PQCrypto::Signature.details(pq_crypto_algorithm)
-          expected = details[:signature_bytes] || details["signature_bytes"]
+          expected = PQCrypto::Signature.details(pq_crypto_algorithm)[:signature_bytes]
           expected.nil? || signature.bytesize == expected
-        rescue StandardError
-          true
+        rescue *VERIFY_ERRORS
+          false
         end
       end
     end