jwt-pq 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d662c64af196cc33ed4b288a641442317fe49881eef85bfadc2385c0bee7e63f
-  data.tar.gz: 599a753241ae95a168461d1a7f61b2a2b2147da13f1456479758873657fb18f5
+  metadata.gz: 9f2d8f33a8210a14b1c5a15e8ae953b38b88e1d35c05d98cfad97e55943d8879
+  data.tar.gz: 1f486a208212534c7ae06721dbad8d11b28ca492795a6409c7a8ab0cd1dcda07
 SHA512:
-  metadata.gz: c360bb8b3b5a8fdad530e3cba2f6d3630999d635669d85e5ac57854f746bbf8250559073d258ca2aa95f0f443208aded8c90b68a15f75f58a00370963fa5c943
-  data.tar.gz: e57d739e3567413f845a685caf55305d7704120fee29adf31ab09cbb0a85cbc2b6c0713ad4e85db73c65c1238d323ab04ab5e079adef06f2918a2114fb06aa96
+  metadata.gz: 673adaee5ef237a31b2ce80a7c9a86442b494fcea875ebcb48648d6a42057b13a0afc46ece40a8d648c8b75e7ee25ccdc35a4daeba972850aaacf3d28ee1a014
+  data.tar.gz: c62aae707ac8ffe1b29d994d86a9e581fd634f6349f0345dab0fdad5674a12fd5289ea89b17b99143d97e6d4dd43e722ec1cedc41112aca80588acee2d56bf35

data/.yardopts

@@ -0,0 +1,9 @@
+--markup markdown
+--readme README.md
+--files CHANGELOG.md,SECURITY.md
+--output-dir doc
+--no-private
+--protected
+lib/**/*.rb
+-
+LICENSE

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-04-20
+
+### Added
+
+- `JWT::PQ::JWKSet` for RFC 7517 §5 JWK Sets — parse, serialize, lookup by `kid`, and enumerate keys (#22)
+- Remote JWKS fetcher with TTL cache and ETag/If-None-Match revalidation for interop with identity providers (#24)
+- YARD documentation across the public API surface (`@param`, `@return`, `@raise`, `@example`); `@api private` markers on internals (#21)
+- `SPEC.md` tracking the IETF drafts jwt-pq targets (JOSE/COSE PQC) and the gem's compatibility policy (#28)
+- Fuzz-style tests hardening `JWK` and `JWKSet` import against malformed input (#23)
+- Ruby→Python JWK cross-interop CI job against an independent ML-DSA / FIPS 204 implementation (#19)
+- Thumbprint test verifying `JWK#thumbprint` matches an independent RFC 7638 computation (#18)
+- Weekly liboqs upstream release monitor workflow (#17)
+
+### Fixed
+
+- **Thread safety**: `Key#sign` / `#verify` / `#destroy!` now use a per-instance mutex instead of a class-level one, restoring real parallelism across keys while keeping a single key safe under concurrent use (#25)
+- **Thread safety**: `MlDsa` handle-cache reads are now always synchronized — the previous double-checked pattern relied on Ruby memory-model guarantees that are not portable across implementations (#31)
+- `JWK#thumbprint` now uses `JSON.generate` for the canonical member dictionary instead of string interpolation, eliminating a class of subtle escaping bugs (#27)
+- `EdDSA+ML-DSA` hybrid `verify` no longer short-circuits between the two component verifications — both are always evaluated so neither timing nor error-path behavior leaks which half failed (#26)
+- `HybridKey#destroy!` now wipes the underlying Ed25519 `@keypair` in addition to the ML-DSA half; FFI secret-key buffers are auto-zeroed on GC as a defense-in-depth finalizer (#32)
+- `JWKSet` remote fetcher enforces the body cap during streaming read (not just post-hoc) and documents the URL-provenance contract callers must honor (#33)
+
+### Changed
+
+- `pqc_asn1` dependency tightened to `~> 0.1.0` (patch-only) so a future 0.2.0 with potential API breakage does not silently upgrade (#29)
+- `bin/` directory no longer packaged into the published gem (smaller install footprint) (#29)
+
+### Dependencies
+
+- Bump `ruby/setup-ruby` from 1.301.0 to 1.302.0 (#30)
+
 ## [0.4.0] - 2026-04-19
 
 ### Added
@@ -103,7 +134,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.4.0...HEAD
+[Unreleased]: https://github.com/marcelopazzo/jwt-pq/compare/v0.5.0...HEAD
+[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
 [0.3.0]: https://github.com/marcelopazzo/jwt-pq/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/marcelopazzo/jwt-pq/compare/v0.1.0...v0.2.0

data/Gemfile

@@ -10,6 +10,7 @@ group :development, :test do
   gem "rspec", "~> 3.13"
   gem "rubocop", "~> 1.75"
   gem "rubocop-rspec", "~> 3.0"
+  gem "yard", "~> 0.9"
 end
 
 group :test do

data/README.md

@@ -115,6 +115,63 @@ jwk.export(include_private: true)
 restored = JWT::PQ::JWK.import(jwk_hash)
 ```
 
+### JWK Set (JWKS)
+
+For publishing multiple verification keys (e.g. during key rotation) or
+consuming a remote JWKS endpoint:
+
+```ruby
+# Producer — publish verification keys on /.well-known/jwks.json
+jwks = JWT::PQ::JWKSet.new([key_current, key_next])
+File.write("jwks.json", jwks.to_json)
+
+# Consumer — resolve the verification key by kid
+jwks = JWT::PQ::JWKSet.import(JSON.parse(fetch_jwks))
+_payload, header = JWT.decode(token, nil, false)        # unverified peek
+key = jwks[header["kid"]] or raise "unknown kid"
+payload, = JWT.decode(token, key, true, algorithms: [header["alg"]])
+```
+
+Members are indexed by their RFC 7638 thumbprint (the same value
+`JWK#export` emits as `kid`). Remember to set the `kid` header when
+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.
+
+### Fetching a remote JWKS
+
+For consuming a JWKS from an identity provider or sibling service,
+`JWT::PQ::JWKSet.fetch` wraps `Net::HTTP` with a TTL cache and
+`ETag`-based revalidation:
+
+```ruby
+jwks = JWT::PQ::JWKSet.fetch("https://issuer.example/.well-known/jwks.json")
+
+_payload, header = JWT.decode(token, nil, false)
+key = jwks[header["kid"]] or raise "unknown kid"
+payload, = JWT.decode(token, key, true, algorithms: [header["alg"]])
+```
+
+The cache is process-global and keyed by URL, so repeated calls inside
+the TTL window (default: 300 s) return the cached set without touching
+the network. Once the TTL expires, the next call issues a conditional
+GET with `If-None-Match`; a `304 Not Modified` refreshes the cache
+timestamp without re-parsing. Tune via kwargs:
+
+```ruby
+JWT::PQ::JWKSet.fetch(url,
+  cache_ttl: 600,         # seconds; default 300
+  timeout: 3,             # read timeout; default 5
+  open_timeout: 3,        # connect timeout; default 5
+  max_body_bytes: 65_536, # response body cap; default 1 MB
+  allow_http: false)      # reject plain http:// (default)
+```
+
+Defense-in-depth defaults: HTTPS only, redirects rejected, body capped
+at 1 MB, 5 s timeouts. Network/HTTP failures raise
+`JWT::PQ::JWKSFetchError`; malformed JWKS bodies raise
+`JWT::PQ::KeyError`.
+
 ## Algorithms
 
 | Algorithm | NIST Level | Public Key | Signature | JWT `alg` value |
@@ -129,7 +186,55 @@ restored = JWT::PQ::JWK.import(jwk_hash)
 
 The hybrid algorithms (`EdDSA+ML-DSA-{44,65,87}`) provide defense-in-depth: if either algorithm is broken, the other still protects the token.
 
-The `alg` header values follow a `ClassicAlg+PQAlg` convention. The IETF draft `draft-ietf-cose-dilithium` is still evolving — these values may change in future versions to align with the final standard.
+The `alg` header values follow a `ClassicAlg+PQAlg` convention. The IETF draft [`draft-ietf-cose-dilithium`](https://datatracker.ietf.org/doc/draft-ietf-cose-dilithium/) is still evolving — these values may change in future versions to align with the final standard.
+
+## Correctness
+
+- **NIST ACVP known-answer tests.** `spec/jwt/pq/kat_spec.rb` runs the full sigVer KAT subset shipped with liboqs against `JWT::PQ::Key#verify` for ML-DSA-44/65/87, covering both positive and negative cases. These vectors are executed in CI on every push. (sigGen KATs are not used because FIPS 204 specifies hedged signing with internal randomness, which makes signature output non-deterministic.)
+- **Cross-language interop.** The [`Cross-interop`](https://github.com/marcelopazzo/jwt-pq/actions/workflows/interop.yml) workflow signs with `jwt-pq` and verifies with [`dilithium-py`](https://pypi.org/project/dilithium-py/), and vice versa, for all three parameter sets. It runs on every push and weekly on `cron`.
+
+## Performance
+
+Measured with `bench/sign_throughput.rb` / `bench/verify_throughput.rb` (and the hybrid variants) using `benchmark-ips`. Hardware: Intel Core i9-9880H @ 2.30 GHz, macOS, Ruby 3.4.6, bundled liboqs 0.15.0, single-threaded.
+
+| Algorithm | Sign | Verify |
+|---|---|---|
+| ML-DSA-44 | 8,026 ops/s (125 µs) | 11,074 ops/s (90 µs) |
+| ML-DSA-65 | 5,972 ops/s (167 µs) | 9,339 ops/s (107 µs) |
+| ML-DSA-87 | 4,911 ops/s (204 µs) | 6,471 ops/s (155 µs) |
+| EdDSA+ML-DSA-65 | 4,695 ops/s (213 µs) | 3,924 ops/s (255 µs) |
+
+Numbers are illustrative — rerun `bundle exec ruby bench/sign_throughput.rb` on your target hardware before capacity-planning. ML-DSA is ~1–2 orders of magnitude slower than Ed25519 (~70 k sigs/s on the same box); plan accordingly.
+
+## Backends
+
+ML-DSA operations are delegated to [liboqs](https://github.com/open-quantum-safe/liboqs), bundled and compiled during `gem install`. An alternative OpenSSL 3.5+ backend is tracked in [#14](https://github.com/marcelopazzo/jwt-pq/issues/14) and will be added once OpenSSL 3.5 ships widely in distros.
+
+## Specification tracking
+
+jwt-pq targets the current IETF specs for JOSE/COSE post-quantum signatures:
+
+- [`draft-ietf-cose-dilithium`](https://datatracker.ietf.org/doc/draft-ietf-cose-dilithium/) — ML-DSA in JOSE/COSE, including the `AKP` key type *(draft)*
+- [RFC 9864](https://datatracker.ietf.org/doc/rfc9864/) — Fully-Specified Algorithms for JOSE and COSE *(published October 2025)*
+- [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final) — ML-DSA itself *(final)*
+
+See [SPEC.md](SPEC.md) for the full tracked-specs table, the current-draft revisions the shipped `alg`/`kty` values target, the hybrid-mode convention, known divergences, and the compatibility policy for draft transitions and the eventual RFC finalization.
+
+## Thread safety
+
+`JWT::PQ::Key` and `JWT::PQ::HybridKey` are safe to share across threads for `#sign`, `#verify`, `#destroy!`, and `Key#private_to_pem` (hybrid sign also covers the Ed25519 + ML-DSA compound atomically). Each instance carries its own mutex that serializes those operations against each other, so a concurrent `#destroy!` waits for any in-flight signing/verification/PEM export to finish before zeroing the private key material. Read-only exporters on immutable state (`#to_pem`, `#public_key`, `#algorithm`, `#jwk_thumbprint`) do not take the mutex.
+
+The mutex cost is negligible against ML-DSA signing latency (~130–200 µs): single-threaded ML-DSA-65 throughput stays within run-to-run noise of the pre-mutex baseline (~7300 sigs/s on an i9-9880H). Under MRI the GVL already serializes signing within a single process; the mutex exists to guarantee atomicity against `destroy!`, not to extract parallelism.
+
+**Fork caveat.** A Mutex held by a live thread at `fork(2)` time is inherited locked-with-no-owner in the child. If you fork workers (Puma, Unicorn, Resque, etc.), do so before any thread begins signing on a shared `Key`, or let each worker construct its own keys post-fork. Do not call `destroy!` on a parent-side key and then fork.
+
+## Algorithm registration
+
+`require "jwt/pq"` registers `ML-DSA-{44,65,87}` and `EdDSA+ML-DSA-{44,65,87}` with ruby-jwt via the **public** `JWT::JWA::SigningAlgorithm.register_algorithm` API — this is not a monkey-patch. The registration is idempotent and coexists with other custom algorithms (e.g. `jwt-eddsa`). Load order between `jwt` and `jwt/pq` does not matter.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for the supported-versions policy, vulnerability reporting process, and how upstream liboqs advisories are handled.
 
 ## Development
 

data/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+## Supported versions
+
+jwt-pq is pre-1.0. Only the latest minor release receives security fixes.
+
+| Version | Supported |
+|---------|-----------|
+| 0.5.x   | Yes       |
+| < 0.5   | No        |
+
+## Reporting a vulnerability
+
+Please **do not** open a public GitHub issue for security problems.
+
+Report privately via GitHub's [private vulnerability reporting](https://github.com/marcelopazzo/jwt-pq/security/advisories/new) or by email to `security@marcelopazzo.com`.
+
+Include:
+
+- Affected version(s)
+- Reproduction steps or proof of concept
+- Impact assessment (key recovery, signature forgery, denial of service, etc.)
+
+You should receive an acknowledgement within **72 hours**. A fix or mitigation plan will follow within **14 days** for high-severity issues.
+
+## Scope
+
+In scope:
+
+- Signature forgery, key recovery, or authentication bypass in `JWT::PQ::Key`, `JWT::PQ::HybridKey`, or the JWT algorithm adapters
+- JWK/PEM parsers accepting malformed input in a way that leaks private key material or enables forgery
+- Memory safety issues in the FFI layer (e.g. out-of-bounds reads through user-controlled inputs)
+
+Out of scope (report upstream):
+
+- Vulnerabilities in [liboqs](https://github.com/open-quantum-safe/liboqs) itself — report to the liboqs maintainers
+- Vulnerabilities in [ruby-jwt](https://github.com/jwt/ruby-jwt), [ed25519](https://github.com/RubyCrypto/ed25519), or [pqc_asn1](https://github.com/msuliq/pqc_asn1) — report to those projects
+
+## Upstream liboqs advisories
+
+jwt-pq bundles a pinned version of liboqs (see `LIBOQS_VERSION` in `ext/jwt/pq/extconf.rb`, currently **0.15.0**, integrity-checked against a SHA-256 of the source tarball).
+
+When [liboqs](https://github.com/open-quantum-safe/liboqs/security/advisories) publishes a security advisory affecting an algorithm we ship:
+
+1. A patch release of jwt-pq will bump `LIBOQS_VERSION` to the fixed upstream version.
+2. The release will be cut within **7 days** of the liboqs advisory for high-severity issues, **30 days** for medium/low.
+3. The changelog entry and GitHub Release notes will link to the upstream advisory.
+
+Users running with `--use-system-libraries` are responsible for upgrading the system liboqs themselves.
+
+## Cryptographic notes
+
+- ML-DSA operations (keygen, sign, verify) are delegated to liboqs in C. jwt-pq does not reimplement the algorithm.
+- Private key material is wiped via `#destroy!` on `JWT::PQ::Key` / `JWT::PQ::HybridKey`, and during PEM import via `PqcAsn1::SecureBuffer`.
+- jwt-pq does not perform manual constant-time comparisons on signatures or MACs — signature verification returns a boolean from liboqs, and there are no equality checks on key/signature bytes in the Ruby layer.
+- Randomness for keygen and signing is sourced from liboqs' internal RNG (which uses the system CSPRNG).

data/SPEC.md

@@ -0,0 +1,72 @@
+# Specification tracking
+
+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
+
+Last reviewed: **2026-04-20**.
+
+| Spec                                                                                    | Role in jwt-pq                                                                                 | Status                      |
+|-----------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------|-----------------------------|
+| [FIPS 204](https://csrc.nist.gov/pubs/fips/204/final)                                   | ML-DSA itself — key generation, signing, verification, key sizes                               | Final (August 2024)         |
+| [RFC 9864](https://datatracker.ietf.org/doc/rfc9864/)                                   | Fully-Specified Algorithms for JOSE and COSE — underlies the `AKP` key type concept            | Final (October 2025)        |
+| [RFC 7515](https://www.rfc-editor.org/rfc/rfc7515) / [RFC 7517](https://www.rfc-editor.org/rfc/rfc7517) / [RFC 7518](https://www.rfc-editor.org/rfc/rfc7518) / [RFC 7638](https://www.rfc-editor.org/rfc/rfc7638) | JWS wire format, JWK structure, `alg` registration, JWK thumbprints                            | Final                       |
+| [`draft-ietf-cose-dilithium`](https://datatracker.ietf.org/doc/draft-ietf-cose-dilithium/) | `AKP` (`"Algorithm Key Pair"`) JWK key type and ML-DSA JWS `alg` names (`ML-DSA-44/65/87`)     | Internet-Draft, pre-RFC     |
+
+The hybrid mode (`EdDSA+ML-DSA-*`) is jwt-pq's own convention —
+concatenated `Ed25519 || ML-DSA` signatures with a `pq_alg` header for
+cross-impl disambiguation. There is no IETF draft that specifies this
+exact shape for EdDSA+ML-DSA; it is implemented here as an interop-safe
+stepping stone until the JOSE WG publishes one.
+
+## Known divergences from the specs
+
+None at the time of writing. jwt-pq implements the ML-DSA JOSE convention
+as currently written in the draft. Any divergence introduced in the
+future (e.g. to work around an ambiguous draft point) will be listed
+here with a link to the commit that introduced it.
+
+## Compatibility policy
+
+Because `draft-ietf-cose-dilithium` is an evolving Internet-Draft and
+not yet an RFC, the `alg`, `kty`, and `pub`/`priv` field semantics can
+change between draft revisions. Our policy for adapting to them:
+
+1. **Pre-1.0 (current).** A breaking change in the draft that requires
+   a wire-format change — renamed `kty`, renamed `alg`, field moved to
+   a different section — ships in a new **minor** version (`0.4 → 0.5`).
+   The CHANGELOG entry will call it out as breaking and name the draft
+   revision motivating the change.
+
+2. **Post-1.0.** The same class of breaking change ships in a new
+   **major** version (`1.x → 2.x`). Minor versions may add support for
+   a new draft revision side-by-side with the old one if doing so does
+   not break wire-compatible deployments.
+
+3. **Overlap window for in-flight drafts.** Where feasible we accept
+   both the previous and the current draft's field names on the import
+   side (`JWK.import`, `from_pem`) for one minor version following a
+   change, and emit only the current draft's form on the export side.
+   This gives operators a migration window without requiring a
+   flag-day rollout.
+
+4. **Final RFC.** When `draft-ietf-cose-dilithium` is published as an
+   RFC, jwt-pq will bump to the RFC's final field names on the export
+   side in a minor (pre-1.0) or major (post-1.0) release, and document
+   the RFC reference here. The import side will continue accepting the
+   last draft revision for at least one further minor to ease
+   migration.
+
+## Reporting divergences
+
+If you find a place where jwt-pq's output does not match the spec,
+please open an issue with:
+
+- The jwt-pq version (`JWT::PQ::VERSION`)
+- The spec section and line/field that disagrees
+- A minimal example showing the difference (e.g. a JWK hash produced by
+  jwt-pq alongside what the spec requires)
+
+Correctness issues are prioritized over feature work.

data/jwt-pq.gemspec

@@ -36,7 +36,7 @@ Gem::Specification.new do |spec|
 
   spec.files = Dir.chdir(__dir__) do
     `git ls-files -z`.split("\x0").reject do |f|
-      f.start_with?("spec/", "vendor/", ".github/", "bench/") ||
+      f.start_with?("spec/", "vendor/", ".github/", "bench/", "bin/") ||
         f.match?(/\A(?:\.git|\.rspec|\.rubocop|jwt-pq-plan)/)
     end
   end
@@ -46,5 +46,8 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency "ffi", "~> 1.15"
   spec.add_dependency "jwt", "~> 3.0"
-  spec.add_dependency "pqc_asn1", "~> 0.1"
+  # Pre-1.0 crypto dependency: tightened to `~> 0.1.0` (patch-only) so a
+  # 0.2.0 release with a potential API break does not silently upgrade.
+  # Bump manually after vetting each new minor.
+  spec.add_dependency "pqc_asn1", "~> 0.1.0"
 end

data/lib/jwt/pq/algorithms/hybrid_eddsa.rb

@@ -5,11 +5,16 @@ require "jwt"
 module JWT
   module PQ
     module Algorithms
+      # @api private
+      #
       # JWT signing algorithm for hybrid EdDSA + ML-DSA signatures.
       #
       # The signature is a simple concatenation: ed25519_sig (64 bytes) || ml_dsa_sig.
       # This allows PQ-aware verifiers to validate both, while the fixed 64-byte
       # Ed25519 prefix makes it possible to split the signatures deterministically.
+      #
+      # Users interact with these algorithms via `JWT.encode`/`JWT.decode` by
+      # name (`"EdDSA+ML-DSA-*"`); they never instantiate this class directly.
       class HybridEdDsa
         include ::JWT::JWA::SigningAlgorithm
 
@@ -34,11 +39,11 @@ module JWT
           end
           raise_sign_error!("Both Ed25519 and ML-DSA private keys required") unless signing_key.private?
 
-          ed_sig = signing_key.ed25519_signing_key.sign(data)
-          ml_sig = signing_key.ml_dsa_key.sign(data)
-
-          # Concatenate: Ed25519 (64 bytes) || ML-DSA (variable)
-          ed_sig + ml_sig
+          # Delegate to HybridKey#sign so the Ed25519 and ML-DSA halves
+          # are taken atomically under the hybrid key's mutex — a
+          # concurrent destroy! can no longer slip between the two
+          # component signatures.
+          signing_key.sign(data)
         end
 
         def verify(data:, signature:, verification_key:)
@@ -53,46 +58,32 @@ module JWT
           ed_sig = signature.byteslice(0, ED25519_SIG_SIZE)
           ml_sig = signature.byteslice(ED25519_SIG_SIZE..)
 
-          ed_valid = begin
-            verification_key.ed25519_verify_key.verify(ed_sig, data)
-            true
-          rescue Ed25519::VerifyError
-            false
-          end
-
+          ed_valid = safe_ed25519_verify(verification_key.ed25519_verify_key, ed_sig, data)
           ml_valid = verification_key.ml_dsa_key.verify(data, ml_sig)
 
-          ed_valid && ml_valid
+          # Bitwise `&`, not `&&`: both checks are already computed above,
+          # and a bitwise AND over booleans has no short-circuit, so the
+          # final combinator does not branch on which half failed. This
+          # does not give a cryptographic constant-time guarantee (Ruby
+          # can't), but it removes the obvious observable path.
+          ed_valid & ml_valid
+        # :nocov: — defensive rescue; Key#verify returns bool, does not raise PQ::Error in practice
         rescue JWT::PQ::Error
           false
+          # :nocov:
         end
 
-        private
-
-        attr_reader :ml_dsa_algorithm
-
-        def resolve_signing_key(key)
-          case key
-          when JWT::PQ::HybridKey
-            raise_sign_error!("Both Ed25519 and ML-DSA private keys required") unless key.private?
-            key
-          else
-            raise_sign_error!(
-              "Expected a JWT::PQ::HybridKey, got #{key.class}. " \
-              "Use JWT::PQ::HybridKey.generate to create a hybrid key."
-            )
-          end
-        end
-
-        def resolve_verification_key(key)
-          case key
-          when JWT::PQ::HybridKey
-            key
-          else
-            raise_verify_error!(
-              "Expected a JWT::PQ::HybridKey, got #{key.class}."
-            )
-          end
+        # Boolean-returning wrapper over `Ed25519::VerifyKey#verify`, which
+        # raises on failure. Gives the verify path a uniform shape for both
+        # halves (both produce a bool by assignment, rather than one via
+        # return value and one via rescue).
+        #
+        # @api private
+        def safe_ed25519_verify(verify_key, signature, data)
+          verify_key.verify(signature, data)
+          true
+        rescue Ed25519::VerifyError
+          false
         end
 
         register_algorithm(new("EdDSA+ML-DSA-44"))

data/lib/jwt/pq/algorithms/ml_dsa.rb

@@ -4,9 +4,17 @@ require "jwt"
 
 module JWT
   module PQ
+    # @api private
+    #
+    # ruby-jwt `SigningAlgorithm` implementations that register jwt-pq's
+    # algorithms on load. Not intended for direct use.
     module Algorithms
+      # @api private
+      #
       # JWT signing algorithm implementation for ML-DSA (FIPS 204).
       # Registers ML-DSA-44, ML-DSA-65, and ML-DSA-87 with the ruby-jwt library.
+      # Users interact with these algorithms via `JWT.encode`/`JWT.decode` by
+      # name; they never instantiate this class directly.
       class MlDsa
         include ::JWT::JWA::SigningAlgorithm
 
@@ -27,8 +35,10 @@ module JWT
             )
           end
           verification_key.verify(data, signature)
+        # :nocov: — defensive rescue; Key#verify returns bool, does not raise PQ::Error in practice
         rescue JWT::PQ::Error
           false
+          # :nocov:
         end
 
         private
@@ -46,18 +56,6 @@ module JWT
           end
         end
 
-        def resolve_verification_key(key)
-          case key
-          when JWT::PQ::Key
-            key
-          else
-            raise_verify_error!(
-              "Expected a JWT::PQ::Key, got #{key.class}. " \
-              "Use JWT::PQ::Key.generate(:#{alg_symbol}) to create a key."
-            )
-          end
-        end
-
         def alg_symbol
           alg.downcase.tr("-", "_")
         end

data/lib/jwt/pq/errors.rb

@@ -2,16 +2,28 @@
 
 module JWT
   module PQ
+    # Base class for all jwt-pq errors.
     class Error < StandardError; end
 
+    # Raised when liboqs reports a failure or is missing at load time.
     class LiboqsError < Error; end
 
+    # Raised when a requested algorithm name is not supported.
     class UnsupportedAlgorithmError < Error; end
 
+    # Raised for malformed keys, wrong key types, or invalid key material.
     class KeyError < Error; end
 
+    # Raised when an optional runtime dependency (e.g. `ed25519` for hybrid
+    # mode) is needed but not installed.
     class MissingDependencyError < Error; end
 
+    # Raised when a signing operation fails inside liboqs.
     class SignatureError < Error; end
+
+    # Raised when a remote JWKS fetch fails — network error, timeout,
+    # non-2xx response, oversized body, or blocked URL (non-HTTPS, redirect).
+    # Parsing failures on the fetched body still surface as {KeyError}.
+    class JWKSFetchError < Error; end
   end
 end