pq_crypto-jwt 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4f383c2f1f0414e4817f80ea6865dc4c9d7acdb512d33e1d3e368b7091f84e9c
+  data.tar.gz: 00ed418f44277af5ec23ae1ffb4be8edf909cf40e6d974cafd072fd2fdbd0c4f
+SHA512:
+  metadata.gz: a1f3e7e7bea52901a570378619485d0d7981129534738e30972187d02c35aa7061bc644c5b6c91ef006a640c9d483993e2d2382447c3b2e8a7205a241b15e922
+  data.tar.gz: c3cc3d4ef8e8b6e73b25cc17bd700f2acfe32b66114cca0b73ee983647856b794824bced8727360769577bbd83e3cc458ce374c2ab00de7886155cbbca46221f

data/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## Initial public release
+
+### Included
+
+- ML-DSA JWS algorithms for `ruby-jwt`:
+  - `ML-DSA-44`
+  - `ML-DSA-65`
+  - `ML-DSA-87`
+- Explicit `PQCrypto::JWT.register!` registration.
+- ML-DSA key generation helper through `PQCrypto::JWT::Keys.generate`.
+- ML-DSA SPKI/PKCS#8 PEM import helpers.
+- Public AKP JWK import/export helpers for ML-DSA verification keys.
+- JWKS construction, lookup, and loader helpers.
+- ML-DSA-65 streaming detached JWS helper.
+- Negative tests for signature tampering, algorithm mismatch, wrong key type, unsupported algorithms, and malformed JWK inputs.
+
+### Deliberately not included
+
+- ML-KEM JWE key agreement or key wrap.
+- 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.
+- Experimental draft behavior that is not ready for interoperability testing.
+
+### Security status
+
+- Unaudited.
+- Backed by `pq_crypto`.
+- Tracks draft ML-DSA JOSE identifiers; identifiers and wire formats may change before RFC publication.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roman Haydarov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,139 @@
+# pq_crypto-jwt
+
+`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:
+
+- 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
+
+ML-KEM/JWE is **not included** in this first release. Full JWE support needs a separate standards-compatible implementation and interoperability tests.
+
+## Install
+
+```ruby
+gem "pq_crypto-jwt", "~> 0.1"
+```
+
+## Register the algorithms
+
+`pq_crypto-jwt` does not register algorithms implicitly. Register once during boot:
+
+```ruby
+require "pq_crypto/jwt"
+
+PQCrypto::JWT.register!
+```
+
+This registers the following JOSE `alg` values with `ruby-jwt`:
+
+```text
+ML-DSA-44
+ML-DSA-65
+ML-DSA-87
+```
+
+## JWS — sign and verify with ML-DSA
+
+```ruby
+require "pq_crypto/jwt"
+
+PQCrypto::JWT.register!
+keypair = PQCrypto::JWT::Keys.generate("ML-DSA-65")
+
+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`.
+
+## PEM import
+
+SPKI public keys and PKCS#8 secret keys can be imported through the helper API:
+
+```ruby
+public_key = PQCrypto::JWT::Keys.public_from_pem(spki_pem)
+secret_key = PQCrypto::JWT::Keys.secret_from_pem(pkcs8_pem)
+
+token = JWT.encode({ "sub" => "alice" }, secret_key, "ML-DSA-65")
+JWT.decode(token, public_key, true, algorithm: "ML-DSA-65")
+```
+
+For stricter dispatch, pass `expect: :signature`:
+
+```ruby
+public_key = PQCrypto::JWT::Keys.public_from_pem(spki_pem, expect: :signature)
+secret_key = PQCrypto::JWT::Keys.secret_from_pem(pkcs8_pem, expect: :signature)
+```
+
+## JWK and JWKS
+
+Public AKP JWK round-trip:
+
+```ruby
+keypair = PQCrypto::JWT::Keys.generate("ML-DSA-65")
+jwk = PQCrypto::JWT::JWK.from_public_key(keypair.public_key, kid: "signing-key")
+public_key = PQCrypto::JWT::JWK.public_key_from_jwk(jwk)
+```
+
+JWKS lookup with `ruby-jwt`:
+
+```ruby
+PQCrypto::JWT.register!
+keypair = PQCrypto::JWT::Keys.generate("ML-DSA-65")
+jwks = PQCrypto::JWT::JWKS.from_keys([keypair.public_key], kids: ["signing-key"])
+
+token = JWT.encode({ "sub" => "alice" }, keypair.secret_key, "ML-DSA-65", kid: "signing-key")
+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.
+
+## 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.
+
+```ruby
+File.open("payload.bin", "rb") do |payload_io|
+  token = PQCrypto::JWT::JWA::MLDSA65.sign_io(
+    signing_key: keypair.secret_key,
+    payload_io: payload_io
+  )
+end
+
+File.open("payload.bin", "rb") do |payload_io|
+  PQCrypto::JWT::JWA::MLDSA65.verify_io!(
+    verification_key: keypair.public_key,
+    token: token,
+    payload_io: payload_io
+  )
+end
+```
+
+## Non-goals for the first release
+
+The first release 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
+- general-purpose JWT claims policy beyond what `ruby-jwt` already provides
+
+This keeps the public API small and avoids publishing draft-incompatible JWE behavior.
+
+## 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.
+```
+
+Use in production only after your own security review and interoperability testing.
+
+## License
+
+MIT.

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../jwa/ml_dsa_44"

data/lib/pq_crypto/jwt/algorithms/ml_dsa_65.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../jwa/ml_dsa_65"

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

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../jwa/ml_dsa_87"

data/lib/pq_crypto/jwt/algorithms.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "jwa"

data/lib/pq_crypto/jwt/errors.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module JWT
+    class Error < StandardError; end
+    class UnsupportedAlgorithm < Error; end
+    class KeyTypeError < Error; end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../jwa"
+
+module PQCrypto
+  module JWT
+    module JWA
+      module MLDSA44
+        extend ::JWT::JWA::SigningAlgorithm
+        extend PQCrypto::JWT::JWA::MLDSA
+
+        ALG = "ML-DSA-44".freeze
+        PQ_CRYPTO_ALGORITHM = :ml_dsa_44
+
+        def self.alg = ALG
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative "../jwa"
+require_relative "ml_dsa_streaming"
+
+module PQCrypto
+  module JWT
+    module JWA
+      module MLDSA65
+        extend ::JWT::JWA::SigningAlgorithm
+        extend PQCrypto::JWT::JWA::MLDSA
+        extend PQCrypto::JWT::JWA::MLDSAStreaming
+
+        ALG = "ML-DSA-65".freeze
+        PQ_CRYPTO_ALGORITHM = :ml_dsa_65
+
+        def self.alg = ALG
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "../jwa"
+
+module PQCrypto
+  module JWT
+    module JWA
+      module MLDSA87
+        extend ::JWT::JWA::SigningAlgorithm
+        extend PQCrypto::JWT::JWA::MLDSA
+
+        ALG = "ML-DSA-87".freeze
+        PQ_CRYPTO_ALGORITHM = :ml_dsa_87
+
+        def self.alg = ALG
+      end
+    end
+  end
+end

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

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "base64"
+require "json"
+
+module PQCrypto
+  module JWT
+    module JWA
+      module MLDSAStreaming
+        DEFAULT_CHUNK_SIZE = 1 << 20
+        EMPTY_CONTEXT = "".b.freeze
+
+        def streaming_supported?
+          pq_crypto_algorithm == :ml_dsa_65 &&
+            PQCrypto::Signature.supported.include?(:ml_dsa_65)
+        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)
+          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(signature)}"
+        rescue PQCrypto::JWT::Error, ArgumentError
+          raise
+        rescue StandardError => e
+          raise ::JWT::EncodeError, e.message
+        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)
+          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
+
+          header = JSON.parse(Base64.urlsafe_decode64(encoded_header))
+          return false unless 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
+
+          [payload_position(payload_io), header]
+        rescue JSON::ParserError, ArgumentError, PQCrypto::InvalidKeyError
+          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
+
+          true
+        end
+
+        private
+
+        def base64url(bytes)
+          Base64.urlsafe_encode64(String(bytes).b, padding: false)
+        end
+
+        def stringify_keys(hash)
+          hash.each_with_object({}) { |(key, value), out| out[String(key)] = value }
+        end
+
+        def payload_position(payload_io)
+          payload_io.respond_to?(:pos) ? payload_io.pos : nil
+        end
+      end
+
+      class DetachedSigningInputIO
+        def initialize(encoded_header, payload_io, chunk_size: MLDSAStreaming::DEFAULT_CHUNK_SIZE)
+          @prefix = "#{encoded_header}.".b
+          @payload_io = payload_io
+          @chunk_size = chunk_size
+          @buffer = +""
+          @carry = +""
+          @prefix_done = false
+          @payload_done = false
+        end
+
+        def read(length = nil, outbuf = nil)
+          length ||= @chunk_size
+          fill(length)
+          return nil if @buffer.empty?
+
+          result = @buffer.byteslice(0, length)
+          @buffer = @buffer.byteslice(result.bytesize..-1) || +""
+          outbuf&.replace(result)
+          outbuf || result
+        end
+
+        private
+
+        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
+        end
+
+        def consume_prefix?
+          return true if @prefix_done
+
+          @prefix_done = true
+          false
+        end
+      end
+    end
+  end
+end

data/lib/pq_crypto/jwt/jwa.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "jwt"
+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
+
+        def verify_io!(**)
+          raise PQCrypto::JWT::UnsupportedAlgorithm, "#{alg} does not support streaming JWS"
+        end
+
+        def key_kind
+          :signature
+        end
+
+        def sign(data:, signing_key:)
+          ensure_secret_key!(signing_key)
+          raise ArgumentError, "data must be a String" unless data.is_a?(String)
+
+          signing_key.sign(data.b)
+        rescue PQCrypto::JWT::KeyTypeError, ArgumentError
+          raise
+        rescue StandardError => e
+          raise ::JWT::EncodeError, e.message
+        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 signature_length_valid?(signature)
+
+          verification_key.verify(data.b, signature.b)
+        rescue PQCrypto::InvalidKeyError, PQCrypto::JWT::Error, ArgumentError
+          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"
+          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
+        end
+
+        def signature_length_valid?(signature)
+          details = PQCrypto::Signature.details(pq_crypto_algorithm)
+          expected = details[:signature_bytes] || details["signature_bytes"]
+          expected.nil? || signature.bytesize == expected
+        rescue StandardError
+          true
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "jwt/jwk/key_base"
+
+module JWT
+  module JWK
+    class AKP < KeyBase
+      KTY = "AKP".freeze
+      KTYS = [
+        KTY,
+        PQCrypto::Signature::PublicKey,
+        JWT::JWK::AKP,
+      ].freeze
+      AKP_KEY_ELEMENTS = %i[kty alg pub priv].freeze
+
+      class NullKidGenerator
+        def initialize(_jwk); end
+
+        def generate = nil
+      end
+
+      def initialize(key, params = nil, options = {})
+        params ||= {}
+        options ||= {}
+        options = { kid_generator: NullKidGenerator }.merge(options)
+        params = { kid: params } if params.is_a?(String)
+        key_params = extract_key_params(key)
+        params = params.transform_keys(&:to_sym)
+        check_jwk_params!(key_params, params)
+        super(options, key_params.merge(params))
+      end
+
+      def private?
+        false
+      end
+
+      def public_key
+        @public_key ||= PQCrypto::JWT::JWK.public_key_from_jwk(string_export)
+      end
+
+      def signing_key
+        public_key
+      end
+
+      def verify_key
+        public_key
+      end
+
+      def export(_options = {})
+        parameters.clone.tap { |exported| exported.delete(:priv) }
+      end
+
+      def members
+        %i[alg kty pub].each_with_object({}) { |key, out| out[key] = self[key] }
+      end
+
+      def key_digest
+        PQCrypto::JWT::JWK.thumbprint(string_export)
+      end
+
+      def jwa
+        PQCrypto::JWT.algorithm_for(self[:alg]) || super
+      end
+
+      def []=(key, value)
+        raise ArgumentError, "cannot overwrite cryptographic key attributes" if AKP_KEY_ELEMENTS.include?(key.to_sym)
+
+        super
+      end
+
+      private
+
+      def string_export
+        export.transform_keys(&:to_s)
+      end
+
+      def extract_key_params(key)
+        case key
+        when JWT::JWK::AKP
+          key.export
+        when Hash
+          key.transform_keys(&:to_sym)
+        when PQCrypto::Signature::PublicKey
+          PQCrypto::JWT::JWK.from_public_key(key).transform_keys(&:to_sym)
+        when PQCrypto::Signature::Keypair, PQCrypto::Signature::SecretKey
+          raise JWT::JWKError, "AKP private JWK export is not supported in the first release"
+        else
+          raise ArgumentError, "key must be a public AKP JWK Hash or PQCrypto::Signature::PublicKey"
+        end
+      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
+        raise JWT::JWKError, "AKP JWK alg is required" unless key_params[:alg]
+        raise JWT::JWKError, "AKP JWK pub is required" unless key_params[:pub]
+        raise JWT::JWKError, "AKP private JWK import is not supported in the first release" if key_params[:priv]
+        raise JWT::JWKError, "Unsupported AKP JWK alg: #{key_params[:alg].inspect}" unless PQCrypto::JWT.algorithm_for(key_params[:alg])
+      end
+    end
+  end
+end
+
+JWT::JWK.classes.delete(JWT::JWK::AKP)

data/lib/pq_crypto/jwt/jwk.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest"
+require "json"
+
+module PQCrypto
+  module JWT
+    module JWK
+      module_function
+
+      KTY = "AKP".freeze
+
+      def from_public_key(public_key, kid: nil)
+        validate_public_key!(public_key)
+        base_public_jwk(public_key.algorithm, public_key.to_bytes, kid: kid).freeze
+      end
+
+      def from_secret_key(*, **)
+        raise PQCrypto::JWT::UnsupportedAlgorithm,
+              "Private AKP JWK export is not supported in the first release; use PEM/PKCS#8 for signing keys"
+      end
+
+      def public_key_from_jwk(hash)
+        jwk = normalize_hash!(hash)
+        reject_private_material!(jwk)
+        algorithm = algorithm_from_jwk!(jwk)
+        public_bytes = decode_required_key_bytes!(jwk, "pub", algorithm, :public_key_bytes)
+        PQCrypto::Signature.public_key_from_bytes(algorithm, public_bytes)
+      rescue ArgumentError => e
+        raise PQCrypto::JWT::Error, e.message
+      end
+
+      def secret_key_from_jwk(*)
+        raise PQCrypto::JWT::UnsupportedAlgorithm,
+              "Private AKP JWK import is not supported in the first release; use PEM/PKCS#8 for signing keys"
+      end
+
+      def thumbprint(jwk_hash)
+        jwk = normalize_hash!(jwk_hash)
+        reject_private_material!(jwk)
+        algorithm_from_jwk!(jwk)
+        raise PQCrypto::JWT::Error, "JWK pub is required" unless jwk.key?("pub")
+
+        canonical = JSON.generate({ "alg" => jwk.fetch("alg"), "kty" => KTY, "pub" => jwk.fetch("pub") })
+        base64url(Digest::SHA256.digest(canonical.b))
+      end
+
+      def base64url(bytes)
+        Base64.urlsafe_encode64(String(bytes).b, padding: false)
+      end
+
+      def base64url_decode(value)
+        Base64.urlsafe_decode64(String(value))
+      rescue ArgumentError => e
+        raise PQCrypto::JWT::Error, "Invalid base64url value: #{e.message}"
+      end
+
+      def normalize_hash!(hash)
+        unless hash.respond_to?(:to_hash)
+          raise PQCrypto::JWT::Error, "JWK must be a Hash-like object"
+        end
+
+        hash.to_hash.each_with_object({}) do |(key, value), normalized|
+          normalized[String(key)] = value
+        end
+      end
+
+      def reject_private_material!(jwk)
+        return unless jwk.key?("priv")
+
+        raise PQCrypto::JWT::UnsupportedAlgorithm,
+              "Private AKP JWK material is not supported in the first release"
+      end
+      private_class_method :reject_private_material!
+
+      def algorithm_from_jwk!(jwk)
+        unless jwk.fetch("kty", nil) == KTY
+          raise PQCrypto::JWT::Error, "Unsupported JWK kty: #{jwk.fetch('kty', nil).inspect}"
+        end
+
+        alg = jwk.fetch("alg", nil)
+        algorithm = PQCrypto::JWT.algorithm_for(alg)
+        raise PQCrypto::JWT::UnsupportedAlgorithm, "Unsupported JWK alg: #{alg.inspect}" unless algorithm
+        raise PQCrypto::JWT::UnsupportedAlgorithm, "Unsupported JWK alg: #{alg.inspect}" unless algorithm.key_kind == :signature
+
+        algorithm.pq_crypto_algorithm
+      end
+
+      def alg_for_algorithm!(algorithm)
+        match = PQCrypto::JWT.signing_algorithms.find { |candidate| candidate.pq_crypto_algorithm == algorithm }
+        raise PQCrypto::JWT::UnsupportedAlgorithm, "Unsupported pq_crypto signature algorithm: #{algorithm.inspect}" unless match
+
+        match.alg
+      end
+
+      def base_public_jwk(algorithm, public_bytes, kid: nil)
+        jwk = {
+          "kty" => KTY,
+          "alg" => alg_for_algorithm!(algorithm),
+          "pub" => base64url(public_bytes),
+        }
+        jwk["kid"] = String(kid) unless kid.nil?
+        jwk
+      end
+      private_class_method :base_public_jwk
+
+      def decode_required_key_bytes!(jwk, field, algorithm, detail_key)
+        raise PQCrypto::JWT::Error, "JWK #{field} is required" unless jwk.key?(field)
+
+        decoded = base64url_decode(jwk.fetch(field))
+        details = PQCrypto::Signature.details(algorithm)
+        expected = details.fetch(detail_key) { details.fetch(detail_key.to_s) }
+        unless decoded.bytesize == expected
+          raise PQCrypto::JWT::Error,
+                "Invalid #{field} length for #{algorithm.inspect}: expected #{expected}, got #{decoded.bytesize}"
+        end
+
+        decoded.b
+      end
+      private_class_method :decode_required_key_bytes!
+
+      def validate_public_key!(public_key)
+        unless public_key.is_a?(PQCrypto::Signature::PublicKey)
+          raise PQCrypto::JWT::KeyTypeError, "Expected PQCrypto::Signature::PublicKey"
+        end
+
+        validate_algorithm!(public_key.algorithm)
+      end
+      private_class_method :validate_public_key!
+
+      def validate_algorithm!(algorithm)
+        return if PQCrypto::JWT.signing_algorithms.any? { |candidate| candidate.pq_crypto_algorithm == algorithm }
+
+        raise PQCrypto::JWT::KeyTypeError, "Unsupported signature algorithm: #{algorithm.inspect}"
+      end
+      private_class_method :validate_algorithm!
+    end
+  end
+end

data/lib/pq_crypto/jwt/jwks.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module JWT
+    module JWKS
+      module_function
+
+      def from_keys(public_keys, kids: nil)
+        keys = Array(public_keys).each_with_index.map do |public_key, index|
+          kid = kids&.fetch(index, nil)
+          PQCrypto::JWT::JWK.from_public_key(public_key, kid: kid)
+        end
+        { "keys" => keys }.freeze
+      end
+
+      def find(jwks, kid: nil, alg: nil)
+        keys_from(jwks).find do |key|
+          (kid.nil? || value_for(key, "kid") == kid) &&
+            (alg.nil? || value_for(key, "alg") == alg)
+        end
+      end
+
+      def loader(jwks_hash_or_callable)
+        cached = nil
+        lambda do |options = {}|
+          if jwks_hash_or_callable.respond_to?(:call)
+            cached = nil if options && options[:invalidate]
+            cached ||= jwks_hash_or_callable.call(options || {})
+          else
+            cached = nil if options && options[:invalidate]
+            cached ||= jwks_hash_or_callable
+          end
+        end
+      end
+
+      def keys_from(jwks)
+        source = jwks.respond_to?(:to_hash) ? jwks.to_hash : jwks
+        keys = source["keys"] || source[:keys] if source.respond_to?(:[])
+        Array(keys).map { |key| stringify_hash(key) }
+      end
+      private_class_method :keys_from
+
+      def stringify_hash(hash)
+        hash.to_hash.each_with_object({}) { |(key, value), out| out[String(key)] = value }
+      end
+      private_class_method :stringify_hash
+
+      def value_for(hash, key)
+        hash[key] || hash[key.to_sym]
+      end
+      private_class_method :value_for
+    end
+  end
+end

data/lib/pq_crypto/jwt/keys.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+require "set"
+
+module PQCrypto
+  module JWT
+    module Keys
+      module_function
+
+      EXPECT_VALUES = [:auto, :signature].freeze
+
+      def generate(alg)
+        algorithm = PQCrypto::JWT.algorithm_for(alg)
+        raise ArgumentError, "Unsupported PQCrypto JOSE algorithm: #{alg.inspect}" unless algorithm
+        raise ArgumentError, "Unsupported key kind for #{alg.inspect}" unless algorithm.key_kind == :signature
+
+        PQCrypto::Signature.generate(algorithm.pq_crypto_algorithm)
+      end
+
+      def public_from_pem(pem, expect: :auto)
+        validate_expect!(expect)
+        return PQCrypto::Signature.public_key_from_spki_pem(pem) if expect == :signature
+
+        dispatch_public_from_pem(pem)
+      end
+
+      def secret_from_pem(pem, expect: :auto)
+        validate_expect!(expect)
+        return PQCrypto::Signature.secret_key_from_pkcs8_pem(pem) if expect == :signature
+
+        dispatch_secret_from_pem(pem)
+      end
+
+      def validate_expect!(expect)
+        return if EXPECT_VALUES.include?(expect)
+
+        raise ArgumentError, "expect: must be one of #{EXPECT_VALUES.map(&:inspect).join(', ')}"
+      end
+      private_class_method :validate_expect!
+
+      def dispatch_public_from_pem(pem)
+        oid = spki_oid_from_pem(pem)
+        return PQCrypto::Signature.public_key_from_spki_pem(pem) if signature_oids.include?(oid.to_s)
+
+        raise PQCrypto::JWT::Error, "Unknown or unsupported PQCrypto SPKI algorithm OID: #{oid.inspect}"
+      end
+      private_class_method :dispatch_public_from_pem
+
+      def dispatch_secret_from_pem(pem)
+        oid = pkcs8_oid_from_pem(pem)
+        return PQCrypto::Signature.secret_key_from_pkcs8_pem(pem) if signature_oids.include?(oid.to_s)
+
+        raise PQCrypto::JWT::Error, "Unknown or unsupported PQCrypto PKCS#8 algorithm OID: #{oid.inspect}"
+      end
+      private_class_method :dispatch_secret_from_pem
+
+      def spki_oid_from_pem(pem)
+        sequence = OpenSSL::ASN1.decode(pem_to_der(pem))
+        sequence.value.fetch(0).value.fetch(0).oid
+      rescue StandardError => e
+        raise PQCrypto::JWT::Error, "Unable to read SPKI algorithm OID: #{e.message}"
+      end
+      private_class_method :spki_oid_from_pem
+
+      def pkcs8_oid_from_pem(pem)
+        sequence = OpenSSL::ASN1.decode(pem_to_der(pem))
+        sequence.value.fetch(1).value.fetch(0).oid
+      rescue StandardError => e
+        raise PQCrypto::JWT::Error, "Unable to read PKCS#8 algorithm OID: #{e.message}"
+      end
+      private_class_method :pkcs8_oid_from_pem
+
+      def pem_to_der(pem)
+        body = pem.to_s.lines.reject { |line| line.start_with?("-----") }.join
+        Base64.decode64(body)
+      end
+      private_class_method :pem_to_der
+
+      def signature_oids
+        @signature_oids ||= PQCrypto::JWT.signing_algorithms.filter_map do |algorithm|
+          oid_for_algorithm(algorithm.pq_crypto_algorithm)
+        end.to_set
+      end
+      private_class_method :signature_oids
+
+      def oid_for_algorithm(algorithm)
+        return unless PQCrypto.const_defined?(:AlgorithmRegistry)
+
+        oid = PQCrypto::AlgorithmRegistry.standard_oid(algorithm)
+        oid&.to_s
+      rescue StandardError
+        nil
+      end
+      private_class_method :oid_for_algorithm
+    end
+  end
+end

data/lib/pq_crypto/jwt/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module PQCrypto
+  module JWT
+    VERSION = "0.1.1"
+  end
+end

data/lib/pq_crypto/jwt.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "jwt"
+require "monitor"
+require "pq_crypto"
+
+require_relative "jwt/version"
+require_relative "jwt/errors"
+require_relative "jwt/jwa"
+require_relative "jwt/jwa/ml_dsa_44"
+require_relative "jwt/jwa/ml_dsa_65"
+require_relative "jwt/jwa/ml_dsa_87"
+require_relative "jwt/keys"
+require_relative "jwt/jwk"
+require_relative "jwt/jwk/akp"
+require_relative "jwt/jwks"
+
+module PQCrypto
+  module JWT
+    MLDSA44 = JWA::MLDSA44
+    MLDSA65 = JWA::MLDSA65
+    MLDSA87 = JWA::MLDSA87
+
+    SIGNING_ALGORITHMS = [JWA::MLDSA44, JWA::MLDSA65, JWA::MLDSA87].freeze
+    KEM_ALGORITHMS = [].freeze
+    ALGORITHMS = SIGNING_ALGORITHMS.freeze
+    ALGORITHMS_BY_JOSE = ALGORITHMS.to_h { |algorithm| [algorithm.alg, algorithm] }.freeze
+
+    class << self
+      def algorithms
+        ALGORITHMS
+      end
+
+      def signing_algorithms
+        SIGNING_ALGORITHMS
+      end
+
+      # Kept as an explicit empty list so callers can branch safely.
+      # ML-KEM/JWE is intentionally not part of the first stable release.
+      def kem_algorithms
+        KEM_ALGORITHMS
+      end
+
+      def algorithm_for(alg_string)
+        ALGORITHMS_BY_JOSE[alg_string]
+      end
+
+      def register!
+        registration_monitor.synchronize do
+          return true if registered?
+
+          SIGNING_ALGORITHMS.each { |algorithm| ::JWT::JWA.register_algorithm(algorithm) }
+          ensure_akp_jwk_registered!
+          @registered = true
+        end
+        true
+      end
+
+      def registered?
+        @registered == true
+      end
+
+      private
+
+      def registration_monitor
+        @registration_monitor ||= Monitor.new
+      end
+
+      def ensure_akp_jwk_registered!
+        classes = ::JWT::JWK.classes
+        classes << ::JWT::JWK::AKP unless classes.include?(::JWT::JWK::AKP)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: pq_crypto-jwt
+version: !ruby/object:Gem::Version
+  version: 0.1.1
+platform: ruby
+authors:
+- Roman Haydarov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pq_crypto
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Ruby-only adapter that adds post-quantum ML-DSA JWS signing and AKP JWK/JWKS
+  helpers to ruby-jwt, backed by pq_crypto.
+email:
+- romanhajdarov@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/pq_crypto/jwt.rb
+- lib/pq_crypto/jwt/algorithms.rb
+- lib/pq_crypto/jwt/algorithms/ml_dsa_44.rb
+- lib/pq_crypto/jwt/algorithms/ml_dsa_65.rb
+- lib/pq_crypto/jwt/algorithms/ml_dsa_87.rb
+- lib/pq_crypto/jwt/errors.rb
+- lib/pq_crypto/jwt/jwa.rb
+- lib/pq_crypto/jwt/jwa/ml_dsa_44.rb
+- lib/pq_crypto/jwt/jwa/ml_dsa_65.rb
+- lib/pq_crypto/jwt/jwa/ml_dsa_87.rb
+- lib/pq_crypto/jwt/jwa/ml_dsa_streaming.rb
+- lib/pq_crypto/jwt/jwk.rb
+- lib/pq_crypto/jwt/jwk/akp.rb
+- lib/pq_crypto/jwt/jwks.rb
+- lib/pq_crypto/jwt/keys.rb
+- lib/pq_crypto/jwt/version.rb
+homepage: https://github.com/roman-haidarov/pq_crypto-jwt
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: ML-DSA JWS algorithms for ruby-jwt backed by pq_crypto
+test_files: []