jwt-pq 0.3.0 → 0.5.0

data/lib/jwt/pq/jwks_loader.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module JWT
+  module PQ
+    class JWKSet
+      # HTTP-backed JWKS loader with TTL cache and ETag revalidation.
+      #
+      # Fetches a remote JWKS document (e.g. `/.well-known/jwks.json`),
+      # parses it via {JWT::PQ::JWKSet.import}, and caches the result
+      # per-URL. Subsequent calls inside the TTL window return the cached
+      # set without touching the network. Once the TTL expires, an
+      # `If-None-Match` conditional GET is issued using the stored
+      # `ETag`; a `304 Not Modified` response refreshes the cache
+      # timestamp without re-parsing.
+      #
+      # Prefer the {JWT::PQ::JWKSet.fetch} shortcut over instantiating
+      # this class directly — it uses a process-global loader so the
+      # cache is shared across callers.
+      #
+      # Defense-in-depth defaults:
+      #
+      # - HTTPS only (pass `allow_http: true` to override for development).
+      # - Redirects are rejected; update the URL to the canonical location.
+      # - Response body is capped at 1 MB (`max_body_bytes`); ML-DSA public
+      #   keys are ~1.3–2.6 KB each, so 1 MB already allows several hundred
+      #   rotation candidates.
+      # - Read/open timeouts default to 5 seconds.
+      # - Failures raise {JWKSFetchError}; parse errors on the fetched body
+      #   surface as {KeyError} from {JWKSet.import}.
+      #
+      # @example Fetch and verify a token
+      #   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"]])
+      class Loader
+        DEFAULT_CACHE_TTL = 300
+        DEFAULT_TIMEOUT = 5
+        DEFAULT_OPEN_TIMEOUT = 5
+        DEFAULT_MAX_BODY_BYTES = 1_048_576
+
+        CacheEntry = Struct.new(:jwks, :etag, :fetched_at)
+        private_constant :CacheEntry
+
+        # @return [Loader] a process-global loader whose cache is shared
+        #   across all {JWKSet.fetch} callers.
+        def self.default
+          @default ||= new
+        end
+
+        # Reset the process-global loader — mainly for tests.
+        # @api private
+        def self.reset_default!
+          @default = nil
+        end
+
+        def initialize
+          @cache = {}
+          @mutex = Mutex.new
+        end
+
+        # Fetch the JWKS at `url`, honouring the cache if the entry is
+        # still fresh.
+        #
+        # **URL provenance.** The URL is used verbatim: `Loader#fetch`
+        # does not resolve DNS, inspect the target IP, or block private,
+        # link-local, or cloud-metadata addresses. Callers are responsible
+        # for ensuring the URL comes from a trusted source (e.g. a pinned
+        # issuer configuration, not untrusted user input) to avoid SSRF.
+        #
+        # @param url [String] the absolute URL of the JWKS document.
+        # @param cache_ttl [Integer] seconds the cached set is considered
+        #   fresh. Default: 300.
+        # @param timeout [Integer] read timeout in seconds. Default: 5.
+        # @param open_timeout [Integer] connect timeout in seconds. Default: 5.
+        # @param max_body_bytes [Integer] cap on response body size.
+        #   Default: 1 MB.
+        # @param allow_http [Boolean] allow plain `http://` URLs. Default:
+        #   false (strongly recommended for production).
+        # @return [JWKSet] the parsed set of verification keys.
+        # @raise [JWKSFetchError] on network error, timeout, non-2xx
+        #   response, oversized body, redirect, or non-HTTPS URL.
+        # @raise [KeyError] if the fetched body is not a valid JWKS.
+        def fetch(url, # rubocop:disable Metrics/ParameterLists
+                  cache_ttl: DEFAULT_CACHE_TTL,
+                  timeout: DEFAULT_TIMEOUT,
+                  open_timeout: DEFAULT_OPEN_TIMEOUT,
+                  max_body_bytes: DEFAULT_MAX_BODY_BYTES,
+                  allow_http: false)
+          uri = validate_uri!(url, allow_http: allow_http)
+
+          fresh = fresh_entry(url, cache_ttl)
+          return fresh.jwks if fresh
+
+          existing = @mutex.synchronize { @cache[url] }
+          result = do_http_get(uri, existing&.etag, timeout, open_timeout, max_body_bytes)
+
+          if result[:not_modified] && existing
+            @mutex.synchronize { existing.fetched_at = now }
+            existing.jwks
+          else
+            jwks = JWKSet.import(result[:body])
+            @mutex.synchronize do
+              @cache[url] = CacheEntry.new(jwks, result[:etag], now)
+            end
+            jwks
+          end
+        end
+
+        # Drop all cached entries.
+        # @return [void]
+        def clear
+          @mutex.synchronize { @cache.clear }
+        end
+
+        # @api private
+        def cached?(url)
+          @mutex.synchronize { @cache.key?(url) }
+        end
+
+        private
+
+        def validate_uri!(url, allow_http:)
+          uri = URI.parse(url)
+          raise JWKSFetchError, "Invalid URL: #{url.inspect} (expected http/https)" unless uri.is_a?(URI::HTTP)
+
+          if uri.scheme == "http" && !allow_http
+            raise JWKSFetchError,
+                  "Refusing non-HTTPS URL #{url.inspect} (pass allow_http: true to override)"
+          end
+          uri
+        rescue URI::InvalidURIError => e
+          raise JWKSFetchError, "Invalid URL: #{e.message}"
+        end
+
+        def fresh_entry(url, cache_ttl)
+          @mutex.synchronize do
+            entry = @cache[url]
+            return nil unless entry
+            return entry if (now - entry.fetched_at) < cache_ttl
+
+            nil
+          end
+        end
+
+        def do_http_get(uri, etag, timeout, open_timeout, max_body_bytes)
+          result = nil
+          perform_request(uri, etag, timeout, open_timeout) do |response|
+            result = handle_response(response, max_body_bytes)
+          end
+          result
+        rescue Net::OpenTimeout, Net::ReadTimeout => e
+          raise JWKSFetchError, "Timeout fetching JWKS from #{uri}: #{e.message}"
+        rescue SocketError, Errno::ECONNREFUSED, Errno::EHOSTUNREACH,
+               Errno::ENETUNREACH, OpenSSL::SSL::SSLError => e
+          raise JWKSFetchError, "Network error fetching JWKS from #{uri}: #{e.message}"
+        end
+
+        # :nocov: — real HTTP path; unit tests stub this method.
+        def perform_request(uri, etag, timeout, open_timeout, &)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = (uri.scheme == "https")
+          http.read_timeout = timeout
+          http.open_timeout = open_timeout
+
+          req = Net::HTTP::Get.new(uri.request_uri)
+          req["Accept"] = "application/jwk-set+json, application/json"
+          req["If-None-Match"] = etag if etag
+
+          http.request(req, &)
+        end
+        # :nocov:
+
+        def handle_response(response, max_body_bytes)
+          case response
+          when Net::HTTPNotModified
+            { not_modified: true }
+          when Net::HTTPSuccess
+            body = read_body_with_cap!(response, max_body_bytes)
+            { not_modified: false, body: body, etag: response["ETag"] }
+          when Net::HTTPRedirection
+            raise JWKSFetchError,
+                  "Refusing to follow redirect to #{response["Location"].inspect}"
+          else
+            raise JWKSFetchError, "HTTP #{response.code} #{response.message}"
+          end
+        end
+
+        # Stream the response body into memory while enforcing the cap
+        # on every chunk. A server that omits `Content-Length` cannot
+        # force unbounded allocation: the accumulator is checked before
+        # and after each append, and the connection is abandoned the
+        # moment the cap is exceeded.
+        def read_body_with_cap!(response, max_body_bytes)
+          declared = response["Content-Length"]&.to_i
+          if declared && declared > max_body_bytes
+            raise JWKSFetchError,
+                  "JWKS body too large: Content-Length #{declared} > #{max_body_bytes}"
+          end
+
+          buffer = String.new(capacity: declared || 0)
+          response.read_body do |chunk|
+            if buffer.bytesize + chunk.bytesize > max_body_bytes
+              raise JWKSFetchError,
+                    "JWKS body too large: exceeded #{max_body_bytes} bytes during streaming read"
+            end
+            buffer << chunk
+          end
+          buffer
+        end
+
+        def now
+          Process.clock_gettime(Process::CLOCK_MONOTONIC).to_i
+        end
+      end
+    end
+  end
+end

data/lib/jwt/pq/key.rb

@@ -4,35 +4,79 @@ require "pqc_asn1"
 
 module JWT
   module PQ
-    # Represents an ML-DSA keypair (public + optional private key).
-    # Used as the signing/verification key for JWT operations.
+    # An ML-DSA keypair (public key + optional private key) used for JWT
+    # signing and verification.
+    #
+    # Prefer the class-level constructors over {.new}:
+    #
+    # - {.generate} — create a fresh keypair
+    # - {.from_pem} — import from a combined SPKI or PKCS#8 PEM
+    # - {.from_pem_pair} — import from separate public/private PEMs
+    # - {.from_public_key} — wrap raw public key bytes (verification only)
+    #
+    # @example Generate and sign
+    #   key = JWT::PQ::Key.generate(:ml_dsa_65)
+    #   token = JWT.encode({ sub: "u-1" }, key, "ML-DSA-65")
+    #
+    # @example Verification-only key
+    #   verifier = JWT::PQ::Key.from_public_key(:ml_dsa_65, pub_bytes)
+    #   JWT.decode(token, verifier, true, algorithms: ["ML-DSA-65"])
     class Key # rubocop:disable Metrics/ClassLength
+      # Symbol → canonical algorithm name.
       ALGORITHM_ALIASES = {
         ml_dsa_44: "ML-DSA-44",
         ml_dsa_65: "ML-DSA-65",
         ml_dsa_87: "ML-DSA-87"
       }.freeze
 
+      # Algorithm name → ASN.1 OID.
       ALGORITHM_OIDS = {
         "ML-DSA-44" => PqcAsn1::OID::ML_DSA_44,
         "ML-DSA-65" => PqcAsn1::OID::ML_DSA_65,
         "ML-DSA-87" => PqcAsn1::OID::ML_DSA_87
       }.freeze
 
+      # ASN.1 OID → algorithm name.
       OID_TO_ALGORITHM = ALGORITHM_OIDS.invert.freeze
 
-      attr_reader :algorithm, :public_key, :private_key
-
+      # @return [String] canonical algorithm name (`"ML-DSA-44"`, `"ML-DSA-65"`, or `"ML-DSA-87"`).
+      attr_reader :algorithm
+
+      # @return [String] raw public key bytes.
+      attr_reader :public_key
+
+      # @return [String, nil] raw private (secret) key bytes, or nil for
+      #   verification-only keys.
+      attr_reader :private_key
+
+      # Low-level constructor. Prefer {.generate}, {.from_pem}, {.from_pem_pair},
+      # or {.from_public_key} in application code.
+      #
+      # @param algorithm [Symbol, String] one of `:ml_dsa_44`, `:ml_dsa_65`,
+      #   `:ml_dsa_87` (or the canonical string form).
+      # @param public_key [String] raw public key bytes of the correct size
+      #   for the algorithm.
+      # @param private_key [String, nil] raw private key bytes, or nil for a
+      #   verification-only key.
+      # @raise [UnsupportedAlgorithmError] if `algorithm` is not recognized.
+      # @raise [KeyError] if a key's byte size does not match the algorithm.
       def initialize(algorithm:, public_key:, private_key: nil)
         @algorithm = resolve_algorithm(algorithm)
         @ml_dsa = MlDsa.new(@algorithm)
         @public_key = public_key
         @private_key = private_key
+        @op_mutex = Mutex.new
 
         validate!
+        init_ffi_buffers!
       end
 
       # Generate a new keypair for the given algorithm.
+      #
+      # @param algorithm [Symbol, String] one of `:ml_dsa_44`, `:ml_dsa_65`,
+      #   `:ml_dsa_87` (or the canonical string form).
+      # @return [Key] a new keypair with both public and private components.
+      # @raise [UnsupportedAlgorithmError] if `algorithm` is not recognized.
       def self.generate(algorithm)
         alg_name = resolve_algorithm(algorithm)
         ml_dsa = MlDsa.new(alg_name)
@@ -41,46 +85,109 @@ module JWT
         new(algorithm: alg_name, public_key: pk, private_key: sk)
       end
 
-      # Create a Key from raw public key bytes (verification only).
+      # Wrap raw public key bytes for verification-only use.
+      #
+      # @param algorithm [Symbol, String] the algorithm the public key belongs to.
+      # @param public_key_bytes [String] raw public key bytes.
+      # @return [Key] a verification-only key ({#private?} returns false).
       def self.from_public_key(algorithm, public_key_bytes)
         new(algorithm: algorithm, public_key: public_key_bytes)
       end
 
       # Sign data using the private key.
+      #
+      # Thread-safe: serialized on a per-instance mutex shared with
+      # {#verify} and {#destroy!}, so a concurrent `destroy!` cannot race
+      # with an in-flight sign. The mutex cost (~hundreds of ns) is
+      # negligible relative to ML-DSA signing (~130–200 µs).
+      #
+      # @param data [String] message bytes to sign.
+      # @return [String] raw signature bytes.
+      # @raise [KeyError] if this key has no private component.
+      # @raise [SignatureError] if liboqs reports a signing failure.
       def sign(data)
-        raise KeyError, "Private key not available — cannot sign" unless @private_key
+        @op_mutex.synchronize do
+          raise KeyError, "Private key not available — cannot sign" unless @sk_buffer
 
-        @ml_dsa.sign_with_sk_buffer(data, sk_buffer)
+          @ml_dsa.sign_with_sk_buffer(data, @sk_buffer)
+        end
       end
 
-      # Verify a signature using the public key.
+      # Verify a signature against data using the public key.
+      #
+      # Thread-safe: serialized on a per-instance mutex shared with
+      # {#sign} and {#destroy!}.
+      #
+      # @param data [String] message bytes that were signed.
+      # @param signature [String] raw signature bytes produced by {#sign}.
+      # @return [Boolean] true if the signature is valid, false otherwise.
       def verify(data, signature)
-        @ml_dsa.verify_with_pk_buffer(data, signature, pk_buffer)
+        @op_mutex.synchronize do
+          @ml_dsa.verify_with_pk_buffer(data, signature, @pk_buffer)
+        end
       end
 
-      # Whether this key can be used for signing.
+      # @return [Boolean] true when this key has a private component and can sign.
       def private?
         !@private_key.nil?
       end
 
       # Zero and discard private key material from Ruby memory.
-      # After calling this, the key can only be used for verification.
+      #
+      # After calling this, {#private?} becomes false and the key can only
+      # be used for verification. Idempotent — safe to call multiple times,
+      # and on verification-only keys.
+      #
+      # Thread-safe: serialized on a per-instance mutex shared with
+      # {#sign} and {#verify}, so `destroy!` waits for any in-flight
+      # signing or verification to complete before zeroing the buffer.
+      #
+      # @return [true]
       def destroy!
-        if @private_key
-          @private_key.replace("\0" * @private_key.bytesize)
-          @private_key = nil
+        @op_mutex.synchronize do
+          if @private_key
+            @private_key.replace("\0" * @private_key.bytesize)
+            @private_key = nil
+          end
+          @sk_buffer&.clear
+          @sk_buffer = nil
         end
-        @sk_buffer&.clear
-        @sk_buffer = nil
         true
       end
 
+      # @return [String] short diagnostic string — never contains key material.
       def inspect
         "#<#{self.class} algorithm=#{@algorithm} private=#{private?}>"
       end
       alias to_s inspect
 
-      # Import a Key from a PEM string (SPKI or PKCS#8).
+      # RFC 7638 JWK Thumbprint for this key, memoized.
+      #
+      # The thumbprint depends only on the canonical JSON of
+      # `{alg, kty, pub}` — all immutable for the lifetime of a Key —
+      # so it is computed lazily on first access and cached. Useful for
+      # callers (e.g. {JWT::PQ::JWKSet}) that index many keys by `kid`
+      # without wanting to allocate a {JWK} wrapper each time.
+      #
+      # Safe to call concurrently on a shared key: the inputs are
+      # immutable post-construction, so a concurrent first access at
+      # worst recomputes the same deterministic string; the `||=`
+      # assignment is a single atomic reference write on MRI.
+      #
+      # @return [String] base64url-encoded SHA-256 thumbprint.
+      def jwk_thumbprint
+        @jwk_thumbprint ||= JWT::PQ::JWK.compute_thumbprint(@algorithm, @public_key)
+      end
+
+      # Import a Key from a PEM string.
+      #
+      # Accepts both SPKI (public-only) and PKCS#8 (private + embedded public)
+      # PEM documents. For a PKCS#8 PEM that does not carry the public key,
+      # use {.from_pem_pair} with a separate public PEM instead.
+      #
+      # @param pem_string [String] a PEM-encoded key document.
+      # @return [Key] a public-only or full keypair, depending on the PEM format.
+      # @raise [KeyError] for unknown OIDs or PKCS#8 PEMs missing the public key.
       def self.from_pem(pem_string)
         info = PqcAsn1::DER.parse_pem(pem_string)
         alg_name = resolve_oid!(info.oid)
@@ -88,13 +195,24 @@ module JWT
         case info.format
         when :spki  then new(algorithm: alg_name, public_key: info.key)
         when :pkcs8 then build_from_pkcs8(info, alg_name)
+        # :nocov: — defensive guard; PqcAsn1::DER.parse_pem only returns :spki or :pkcs8
         else raise KeyError, "Unsupported PEM format: #{info.format}"
+          # :nocov:
         end
       ensure
         info&.key&.wipe! if info&.format == :pkcs8
       end
 
       # Import a Key from separate public and private PEM strings.
+      #
+      # Use this when your private PEM is PKCS#8 without an embedded public
+      # key, or when public and private material come from different sources.
+      #
+      # @param public_pem [String] SPKI-encoded public key PEM.
+      # @param private_pem [String] PKCS#8-encoded private key PEM.
+      # @return [Key] a full keypair.
+      # @raise [KeyError] if the OIDs are unknown or the public and private
+      #   PEMs specify different algorithms.
       def self.from_pem_pair(public_pem:, private_pem:)
         pub_info = PqcAsn1::DER.parse_pem(public_pem)
         priv_info = PqcAsn1::DER.parse_pem(private_pem)
@@ -112,26 +230,43 @@ module JWT
         priv_info&.key&.wipe!
       end
 
-      # Export the public key as PEM (SPKI format).
+      # Export the public key as an SPKI PEM string.
+      #
+      # @return [String] a `-----BEGIN PUBLIC KEY-----` PEM document.
       def to_pem
         oid = ALGORITHM_OIDS[@algorithm]
         der = PqcAsn1::DER.build_spki(oid, @public_key)
         PqcAsn1::PEM.encode(der, "PUBLIC KEY")
       end
 
-      # Export the private key as PEM (PKCS#8 format).
+      # Export the private key as a PKCS#8 PEM string.
+      #
+      # The PEM carries both the private key and the public key (so the pair
+      # can later be re-imported with {.from_pem} alone).
+      #
+      # Thread-safe: the read of `@private_key` and the DER build are
+      # serialized against {#destroy!} on the per-instance mutex, so a
+      # concurrent `destroy!` cannot zero the bytes mid-encode.
+      #
+      # @return [String] a `-----BEGIN PRIVATE KEY-----` PEM document.
+      # @raise [KeyError] if this key has no private component.
       def private_to_pem
-        raise KeyError, "Private key not available" unless @private_key
+        @op_mutex.synchronize do
+          raise KeyError, "Private key not available" unless @private_key
 
-        oid = ALGORITHM_OIDS[@algorithm]
-        secure_der = PqcAsn1::DER.build_pkcs8(oid, @private_key, public_key: @public_key)
-        secure_der.to_pem
+          oid = ALGORITHM_OIDS[@algorithm]
+          secure_der = PqcAsn1::DER.build_pkcs8(oid, @private_key, public_key: @public_key)
+          secure_der.to_pem
+        end
       end
 
+      # @api private
       def self.resolve_algorithm(algorithm)
         ALGORITHM_ALIASES.fetch(algorithm.to_sym) { algorithm.to_s }
       end
 
+      # @api private
+      #
       # Extract bytes from a PqcAsn1::SecureBuffer using the safe block API.
       # The yielded String shares the SecureBuffer's C-level memory, so
       # String.new / dup / b all get zeroed when the block exits.
@@ -140,10 +275,12 @@ module JWT
         secure_buffer.use { |bytes| bytes.bytes.pack("C*") }
       end
 
+      # @api private
       def self.resolve_oid!(oid)
         OID_TO_ALGORITHM[oid] || raise(KeyError, "Unknown OID in PEM: #{oid.dotted}")
       end
 
+      # @api private
       def self.build_from_pkcs8(info, alg_name)
         raise KeyError, "PKCS#8 PEM for #{alg_name} missing public key. Use from_pem_pair." unless info.public_key
 
@@ -151,16 +288,41 @@ module JWT
         new(algorithm: alg_name, public_key: info.public_key, private_key: sk_bytes)
       end
 
+      # @api private
+      #
+      # Build a GC finalizer that zeros the given FFI buffer before it is
+      # freed. Defined at the class level so the returned proc closes over
+      # the buffer only — capturing `self` would keep the Key alive forever
+      # and the finalizer would never run. Calling `.clear` on an already
+      # zeroed buffer (after an explicit {#destroy!}) is a safe no-op.
+      private_class_method def self.finalizer_for(sk_buffer)
+        proc { sk_buffer.clear }
+      end
+
       private_class_method :resolve_algorithm, :extract_secure_bytes, :resolve_oid!, :build_from_pkcs8
 
       private
 
-      def sk_buffer
-        @sk_buffer ||= FFI::MemoryPointer.new(:uint8, @private_key.bytesize).put_bytes(0, @private_key)
-      end
+      # Allocate and populate the FFI buffers for the public key and (when
+      # present) the private key. Done eagerly at construction time to
+      # avoid a thread-safety race on lazy initialization: `@var ||= ...`
+      # is not atomic under MRI, so two threads concurrently calling
+      # {#sign} on a fresh key could each allocate separate
+      # FFI::MemoryPointers holding a copy of the secret key; the loser's
+      # copy then lingers in memory until GC, unzeroed. Eager init makes
+      # each Key hold exactly one copy of each key buffer for its lifetime.
+      #
+      # A GC finalizer zeros `@sk_buffer` before FFI releases its memory,
+      # so a forgotten {#destroy!} cannot leak secret key bytes to the
+      # allocator. {#destroy!} remains the preferred explicit path; the
+      # finalizer is a last-resort safety net. The finalizer closes over
+      # the buffer only — not `self` — so it does not pin the Key from GC.
+      def init_ffi_buffers!
+        @pk_buffer = FFI::MemoryPointer.new(:uint8, @public_key.bytesize).put_bytes(0, @public_key)
+        return unless @private_key
 
-      def pk_buffer
-        @pk_buffer ||= FFI::MemoryPointer.new(:uint8, @public_key.bytesize).put_bytes(0, @public_key)
+        @sk_buffer = FFI::MemoryPointer.new(:uint8, @private_key.bytesize).put_bytes(0, @private_key)
+        ObjectSpace.define_finalizer(self, self.class.send(:finalizer_for, @sk_buffer))
       end
 
       def resolve_algorithm(algorithm)

data/lib/jwt/pq/liboqs.rb

@@ -4,6 +4,8 @@ require "ffi"
 
 module JWT
   module PQ
+    # @api private
+    #
     # FFI bindings for liboqs signature operations.
     #
     # Library search order:
@@ -40,12 +42,14 @@ module JWT
       begin
         ffi_lib lib_path
       rescue LoadError => e
+        # :nocov: — reached only when liboqs is missing at module load
         raise JWT::PQ::LiboqsError,
               "liboqs not found. The vendored library may not have been compiled " \
               "during gem install. Ensure cmake and a C compiler are installed, " \
               "then reinstall: gem install jwt-pq. Alternatively, install liboqs " \
               "manually and set OQS_LIB to the full path. " \
               "Original error: #{e.message}"
+        # :nocov:
       end
 
       # OQS_SIG *OQS_SIG_new(const char *method_name)

data/lib/jwt/pq/ml_dsa.rb

@@ -2,6 +2,8 @@
 
 module JWT
   module PQ
+    # @api private
+    #
     # Ruby wrapper around liboqs ML-DSA operations.
     # Handles memory allocation, FFI calls, and cleanup.
     class MlDsa
@@ -15,7 +17,7 @@ module JWT
       @sign_handles_mutex = Mutex.new
 
       def self.sign_handle(algorithm)
-        @sign_handles[algorithm] || @sign_handles_mutex.synchronize do
+        @sign_handles_mutex.synchronize do
           @sign_handles[algorithm] ||= begin
             h = LibOQS.OQS_SIG_new(algorithm)
             raise LiboqsError, "Failed to initialize #{algorithm}" if h.null?
@@ -29,7 +31,7 @@ module JWT
       @verify_handles_mutex = Mutex.new
 
       def self.verify_handle(algorithm)
-        @verify_handles[algorithm] || @verify_handles_mutex.synchronize do
+        @verify_handles_mutex.synchronize do
           @verify_handles[algorithm] ||= begin
             h = LibOQS.OQS_SIG_new(algorithm)
             raise LiboqsError, "Failed to initialize #{algorithm}" if h.null?
@@ -39,6 +41,25 @@ module JWT
         end
       end
 
+      # Drop the process-wide cache of `OQS_SIG` handles.
+      #
+      # The first call to {.sign_handle} or {.verify_handle} in a process
+      # (or after this reset) lazily allocates a fresh handle. The
+      # inherited handles in the child are not explicitly freed — doing
+      # so can confuse `malloc` bookkeeping across forked processes. The
+      # handles leak until process exit (≤3 algorithms × <1 KB each),
+      # which is negligible.
+      #
+      # Prefer the public {JWT::PQ.reset_handles!} wrapper from
+      # application code.
+      #
+      # @api private
+      # @return [void]
+      def self.reset_handles!
+        @sign_handles_mutex.synchronize { @sign_handles.clear }
+        @verify_handles_mutex.synchronize { @verify_handles.clear }
+      end
+
       attr_reader :algorithm
 
       def initialize(algorithm)

data/lib/jwt/pq/version.rb

@@ -2,6 +2,7 @@
 
 module JWT
   module PQ
-    VERSION = "0.3.0"
+    # Current gem version.
+    VERSION = "0.5.0"
   end
 end