jwt-pq 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 50b794a7ae8858987b6ec5608deef2c56e1e7ae89dca00da9e8cfbea14999f06
+  data.tar.gz: a2c66e4bca2430f9f443dcef4d2c8d6a92ce619576ae4c99f1fa61ddef7935aa
+SHA512:
+  metadata.gz: ffb6709911168e143e1babc9d1c2209ab5ceaed573529b801f72ba1d20f13cd26575b8c6db6c754e2028c7e695fe492b5ce052fd5b6b002fa5ee7d530f0ea479
+  data.tar.gz: a2f9e6837f2995d09c67576ab317358cbf32b23349416c127c2d11bbbeb91c5ea81d9c914e6f302bb23bf874cd1cd48714af903d9b663f7e4dea62bb04b135d8

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-04-04
+
+### Added
+
+- ML-DSA-44, ML-DSA-65, and ML-DSA-87 signature algorithms via liboqs FFI
+- JWT signing/verification through `JWT.encode` / `JWT.decode` (ruby-jwt >= 3.0)
+- `JWT::PQ::Key` for keypair generation and management
+- PEM serialization (SPKI/PKCS#8) via pqc_asn1
+- JWK export/import (kty: "AKP") with RFC 7638 thumbprints
+- Hybrid EdDSA + ML-DSA mode (`EdDSA+ML-DSA-{44,65,87}`)
+  - Concatenated signature format: Ed25519 (64B) || ML-DSA
+  - Optional dependency on jwt-eddsa / ed25519
+- Error classes: `LiboqsError`, `KeyError`, `SignatureError`, `MissingDependencyError`

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec
+
+group :development, :test do
+  gem "rspec", "~> 3.13"
+  gem "rubocop", "~> 1.75"
+  gem "rubocop-rspec", "~> 3.0"
+end
+
+group :test do
+  gem "jwt-eddsa", "~> 0.9"
+  gem "simplecov", require: false
+end

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcelo Almeida
+
+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,143 @@
+# jwt-pq
+
+Post-quantum JWT signatures for Ruby. Adds **ML-DSA** (FIPS 204) support to the [ruby-jwt](https://github.com/jwt/ruby-jwt) ecosystem, with an optional **hybrid EdDSA + ML-DSA** mode.
+
+## Features
+
+- ML-DSA-44, ML-DSA-65, and ML-DSA-87 algorithms
+- Hybrid EdDSA + ML-DSA dual signatures
+- Drop-in integration with `JWT.encode` / `JWT.decode`
+- PEM serialization (SPKI / PKCS#8) via [pqc_asn1](https://github.com/msuliq/pqc_asn1)
+- JWK export/import with RFC 7638 thumbprints
+
+## Requirements
+
+- Ruby >= 3.2
+- [liboqs](https://github.com/open-quantum-safe/liboqs) (shared library)
+
+### Installing liboqs
+
+```bash
+# macOS
+brew install cmake ninja
+git clone --depth 1 https://github.com/open-quantum-safe/liboqs
+cd liboqs && mkdir build && cd build
+cmake -GNinja -DBUILD_SHARED_LIBS=ON ..
+ninja && sudo ninja install
+
+# Ubuntu / Debian
+sudo apt-get install cmake ninja-build
+git clone --depth 1 https://github.com/open-quantum-safe/liboqs
+cd liboqs && mkdir build && cd build
+cmake -GNinja -DBUILD_SHARED_LIBS=ON ..
+ninja && sudo ninja install && sudo ldconfig
+```
+
+You can also set the `OQS_LIB` environment variable to point to a custom `liboqs.so` / `liboqs.dylib` path.
+
+## Installation
+
+```ruby
+# Gemfile
+gem "jwt-pq"
+
+# For hybrid EdDSA + ML-DSA mode (optional):
+gem "jwt-eddsa"
+```
+
+## Usage
+
+### Basic ML-DSA signing
+
+```ruby
+require "jwt/pq"
+
+key = JWT::PQ::Key.generate(:ml_dsa_65)
+
+# Encode
+token = JWT.encode({ sub: "1234" }, key, "ML-DSA-65")
+
+# Decode
+decoded = JWT.decode(token, key, true, algorithms: ["ML-DSA-65"])
+decoded.first # => { "sub" => "1234" }
+```
+
+### Verify with public key only
+
+```ruby
+pub_key = JWT::PQ::Key.from_public_key("ML-DSA-65", key.public_key)
+JWT.decode(token, pub_key, true, algorithms: ["ML-DSA-65"])
+```
+
+### Hybrid EdDSA + ML-DSA
+
+Requires `jwt-eddsa` gem.
+
+```ruby
+require "jwt/pq"
+
+hybrid_key = JWT::PQ::HybridKey.generate(:ml_dsa_65)
+
+token = JWT.encode({ sub: "1234" }, hybrid_key, "EdDSA+ML-DSA-65")
+
+# Verify — both Ed25519 and ML-DSA signatures must be valid
+decoded = JWT.decode(token, hybrid_key, true, algorithms: ["EdDSA+ML-DSA-65"])
+```
+
+The hybrid signature is a concatenation of `Ed25519 (64 bytes) || ML-DSA`, stored in the standard JWT signature field. The JWT header includes `"pq_alg": "ML-DSA-65"`.
+
+### PEM serialization
+
+```ruby
+# Export
+pub_pem  = key.to_pem          # SPKI format
+priv_pem = key.private_to_pem  # PKCS#8 format
+
+# Import
+pub_key  = JWT::PQ::Key.from_pem(pub_pem)
+full_key = JWT::PQ::Key.from_pem_pair(public_pem: pub_pem, private_pem: priv_pem)
+```
+
+### JWK
+
+```ruby
+jwk = JWT::PQ::JWK.new(key)
+
+# Export
+jwk.export
+# => { kty: "AKP", alg: "ML-DSA-65", pub: "...", kid: "..." }
+
+jwk.export(include_private: true)
+# => { kty: "AKP", alg: "ML-DSA-65", pub: "...", priv: "...", kid: "..." }
+
+# Import
+restored = JWT::PQ::JWK.import(jwk_hash)
+```
+
+## Algorithms
+
+| Algorithm | NIST Level | Public Key | Signature | JWT `alg` value |
+|-----------|-----------|------------|-----------|-----------------|
+| ML-DSA-44 | 2 | 1,312 B | 2,420 B | `ML-DSA-44` |
+| ML-DSA-65 | 3 | 1,952 B | 3,309 B | `ML-DSA-65` |
+| ML-DSA-87 | 5 | 2,592 B | 4,627 B | `ML-DSA-87` |
+
+**Note on token size:** ML-DSA signatures are significantly larger than classical algorithms. A JWT with ML-DSA-65 will have a ~4.4 KB signature (base64url encoded), compared to ~86 bytes for Ed25519 or ~342 bytes for RS256.
+
+## Hybrid mode details
+
+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.
+
+## Development
+
+```bash
+bundle install
+OQS_LIB=/path/to/liboqs.dylib bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+[MIT](LICENSE)

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/jwt-pq.gemspec

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require_relative "lib/jwt/pq/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "jwt-pq"
+  spec.version = JWT::PQ::VERSION
+  spec.authors = ["Marcelo Almeida"]
+  spec.email = ["contact@marcelopazzo.com"]
+
+  spec.summary = "Post-quantum JWT signatures (ML-DSA / FIPS 204) for Ruby"
+  spec.description = "Adds ML-DSA-44, ML-DSA-65, and ML-DSA-87 post-quantum signature " \
+                     "algorithms to the ruby-jwt ecosystem, with optional hybrid " \
+                     "EdDSA + ML-DSA mode. Uses liboqs via FFI."
+  spec.homepage = "https://github.com/marcelopazzo/jwt-pq"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2"
+
+  spec.metadata = {
+    "source_code_uri" => spec.homepage,
+    "changelog_uri" => "#{spec.homepage}/blob/main/CHANGELOG.md",
+    "bug_tracker_uri" => "#{spec.homepage}/issues",
+    "documentation_uri" => "https://rubydoc.info/gems/jwt-pq",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.requirements = ["liboqs >= 0.15.0 (shared library) — https://github.com/open-quantum-safe/liboqs"]
+
+  spec.post_install_message = <<~MSG
+    jwt-pq requires liboqs (shared library) to be installed on your system.
+    See https://github.com/marcelopazzo/jwt-pq#installing-liboqs for instructions.
+    For hybrid EdDSA+ML-DSA mode, also add 'jwt-eddsa' to your Gemfile.
+  MSG
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.start_with?("spec/", "vendor/", ".github/") ||
+        f.match?(/\A(?:\.git|\.rspec|\.rubocop|jwt-pq-plan)/)
+    end
+  end
+
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "ffi", "~> 1.15"
+  spec.add_dependency "jwt", "~> 3.0"
+  spec.add_dependency "pqc_asn1", "~> 0.1"
+end

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

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "jwt"
+
+module JWT
+  module PQ
+    module Algorithms
+      # 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.
+      class HybridEdDsa
+        include ::JWT::JWA::SigningAlgorithm
+
+        ED25519_SIG_SIZE = 64
+
+        def initialize(alg)
+          @alg = alg
+        end
+
+        def header(*)
+          { "alg" => alg, "pq_alg" => ml_dsa_algorithm }
+        end
+
+        def sign(data:, signing_key:)
+          key = resolve_signing_key(signing_key)
+
+          ed_sig = key.ed25519_signing_key.sign(data)
+          ml_sig = key.ml_dsa_key.sign(data)
+
+          # Concatenate: Ed25519 (64 bytes) || ML-DSA (variable)
+          ed_sig + ml_sig
+        end
+
+        def verify(data:, signature:, verification_key:)
+          key = resolve_verification_key(verification_key)
+
+          return false if signature.bytesize <= ED25519_SIG_SIZE
+
+          ed_sig = signature.byteslice(0, ED25519_SIG_SIZE)
+          ml_sig = signature.byteslice(ED25519_SIG_SIZE..)
+
+          ed_valid = begin
+            key.ed25519_verify_key.verify(ed_sig, data)
+            true
+          rescue Ed25519::VerifyError
+            false
+          end
+
+          ml_valid = key.ml_dsa_key.verify(data, ml_sig)
+
+          ed_valid && ml_valid
+        rescue JWT::PQ::Error
+          false
+        end
+
+        private
+
+        def ml_dsa_algorithm
+          alg.sub("EdDSA+", "")
+        end
+
+        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
+        end
+
+        register_algorithm(new("EdDSA+ML-DSA-44"))
+        register_algorithm(new("EdDSA+ML-DSA-65"))
+        register_algorithm(new("EdDSA+ML-DSA-87"))
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "jwt"
+
+module JWT
+  module PQ
+    module Algorithms
+      # 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.
+      class MlDsa
+        include ::JWT::JWA::SigningAlgorithm
+
+        def initialize(alg)
+          @alg = alg
+        end
+
+        def sign(data:, signing_key:)
+          key = resolve_key(signing_key)
+          raise_sign_error!("Private key required for signing") unless key.private?
+          key.sign(data)
+        end
+
+        def verify(data:, signature:, verification_key:)
+          key = resolve_key(verification_key)
+          key.verify(data, signature)
+        rescue JWT::PQ::Error
+          false
+        end
+
+        private
+
+        def resolve_key(key)
+          case key
+          when JWT::PQ::Key
+            key
+          else
+            raise_sign_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
+
+        register_algorithm(new("ML-DSA-44"))
+        register_algorithm(new("ML-DSA-65"))
+        register_algorithm(new("ML-DSA-87"))
+      end
+    end
+  end
+end

data/lib/jwt/pq/errors.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module JWT
+  module PQ
+    class Error < StandardError; end
+
+    class LiboqsError < Error; end
+
+    class UnsupportedAlgorithmError < Error; end
+
+    class KeyError < Error; end
+
+    class MissingDependencyError < Error; end
+
+    class SignatureError < Error; end
+  end
+end

data/lib/jwt/pq/hybrid_key.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module JWT
+  module PQ
+    # Composite key combining an Ed25519 keypair with an ML-DSA keypair
+    # for hybrid EdDSA + ML-DSA JWT signatures.
+    class HybridKey
+      attr_reader :ed25519_signing_key, :ed25519_verify_key, :ml_dsa_key
+
+      # @param ed25519 [Ed25519::SigningKey, Ed25519::VerifyKey] Ed25519 key
+      # @param ml_dsa [JWT::PQ::Key] ML-DSA key
+      def initialize(ed25519:, ml_dsa:)
+        require_eddsa_dependency!
+
+        @ml_dsa_key = ml_dsa
+
+        case ed25519
+        when Ed25519::SigningKey
+          @ed25519_signing_key = ed25519
+          @ed25519_verify_key = ed25519.verify_key
+        when Ed25519::VerifyKey
+          @ed25519_signing_key = nil
+          @ed25519_verify_key = ed25519
+        else
+          raise KeyError, "Expected Ed25519::SigningKey or Ed25519::VerifyKey, got #{ed25519.class}"
+        end
+      end
+
+      # Generate a new hybrid keypair.
+      def self.generate(ml_dsa_algorithm = :ml_dsa_65)
+        require_eddsa_dependency!
+
+        ed_key = Ed25519::SigningKey.generate
+        ml_key = Key.generate(ml_dsa_algorithm)
+
+        new(ed25519: ed_key, ml_dsa: ml_key)
+      end
+
+      # Whether both keys have private components (can sign).
+      def private?
+        !@ed25519_signing_key.nil? && @ml_dsa_key.private?
+      end
+
+      # The ML-DSA algorithm name (e.g., "ML-DSA-65").
+      def algorithm
+        @ml_dsa_key.algorithm
+      end
+
+      # The hybrid algorithm name (e.g., "EdDSA+ML-DSA-65").
+      def hybrid_algorithm
+        "EdDSA+#{@ml_dsa_key.algorithm}"
+      end
+
+      def self.require_eddsa_dependency!
+        require "ed25519"
+      rescue LoadError
+        raise MissingDependencyError,
+              "The 'jwt-eddsa' gem (or 'ed25519' gem) is required for hybrid " \
+              "EdDSA+ML-DSA mode. Add it to your Gemfile: gem 'jwt-eddsa'"
+      end
+      private_class_method :require_eddsa_dependency!
+
+      private
+
+      def require_eddsa_dependency!
+        self.class.send(:require_eddsa_dependency!)
+      end
+    end
+  end
+end

data/lib/jwt/pq/jwk.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "base64"
+require "openssl"
+
+module JWT
+  module PQ
+    # JWK (JSON Web Key) support for ML-DSA keys.
+    #
+    # Follows the draft-ietf-cose-dilithium conventions:
+    #   kty: "AKP" (Algorithm Key Pair)
+    #   alg: "ML-DSA-44", "ML-DSA-65", or "ML-DSA-87"
+    #   pub: base64url-encoded public key
+    #   priv: base64url-encoded private key (optional)
+    class JWK
+      ALGORITHMS = %w[ML-DSA-44 ML-DSA-65 ML-DSA-87].freeze
+      KTY = "AKP"
+
+      attr_reader :key
+
+      def initialize(key)
+        raise KeyError, "Expected a JWT::PQ::Key, got #{key.class}" unless key.is_a?(JWT::PQ::Key)
+
+        @key = key
+      end
+
+      # Export the key as a JWK hash.
+      def export(include_private: false)
+        jwk = {
+          kty: KTY,
+          alg: @key.algorithm,
+          pub: base64url_encode(@key.public_key),
+          kid: thumbprint
+        }
+
+        jwk[:priv] = base64url_encode(@key.private_key) if include_private && @key.private?
+
+        jwk
+      end
+
+      # Import a Key from a JWK hash.
+      def self.import(jwk_hash)
+        jwk = normalize_keys(jwk_hash)
+
+        validate_kty!(jwk)
+        alg = validate_alg!(jwk)
+        pub_bytes = base64url_decode(jwk["pub"])
+
+        if jwk.key?("priv")
+          priv_bytes = base64url_decode(jwk["priv"])
+          Key.new(algorithm: alg, public_key: pub_bytes, private_key: priv_bytes)
+        else
+          Key.new(algorithm: alg, public_key: pub_bytes)
+        end
+      end
+
+      # JWK Thumbprint (RFC 7638) for key identification.
+      # Uses the required members: alg, kty, pub.
+      def thumbprint
+        canonical = "{\"alg\":\"#{@key.algorithm}\",\"kty\":\"#{KTY}\",\"pub\":\"#{base64url_encode(@key.public_key)}\"}"
+        digest = OpenSSL::Digest::SHA256.digest(canonical)
+        base64url_encode(digest)
+      end
+
+      def self.validate_kty!(jwk)
+        kty = jwk["kty"]
+        raise KeyError, "Missing 'kty' in JWK" unless kty
+        raise KeyError, "Expected kty '#{KTY}', got '#{kty}'" unless kty == KTY
+      end
+      private_class_method :validate_kty!
+
+      def self.validate_alg!(jwk)
+        alg = jwk["alg"]
+        raise KeyError, "Missing 'alg' in JWK" unless alg
+        raise KeyError, "Unsupported algorithm '#{alg}'" unless ALGORITHMS.include?(alg)
+
+        alg
+      end
+      private_class_method :validate_alg!
+
+      def self.normalize_keys(hash)
+        hash.transform_keys(&:to_s)
+      end
+      private_class_method :normalize_keys
+
+      def self.base64url_decode(str)
+        ::Base64.urlsafe_decode64(str)
+      end
+      private_class_method :base64url_decode
+
+      private
+
+      def base64url_encode(bytes)
+        ::Base64.urlsafe_encode64(bytes, padding: false)
+      end
+    end
+  end
+end

data/lib/jwt/pq/key.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+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.
+    class Key
+      ALGORITHM_ALIASES = {
+        ml_dsa_44: "ML-DSA-44",
+        ml_dsa_65: "ML-DSA-65",
+        ml_dsa_87: "ML-DSA-87"
+      }.freeze
+
+      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
+
+      OID_TO_ALGORITHM = ALGORITHM_OIDS.invert.freeze
+
+      attr_reader :algorithm, :public_key, :private_key
+
+      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
+
+        validate!
+      end
+
+      # Generate a new keypair for the given algorithm.
+      def self.generate(algorithm)
+        alg_name = resolve_algorithm(algorithm)
+        ml_dsa = MlDsa.new(alg_name)
+        pk, sk = ml_dsa.keypair
+
+        new(algorithm: alg_name, public_key: pk, private_key: sk)
+      end
+
+      # Create a Key from raw public key bytes (verification only).
+      def self.from_public_key(algorithm, public_key_bytes)
+        new(algorithm: algorithm, public_key: public_key_bytes)
+      end
+
+      # Sign data using the private key.
+      def sign(data)
+        raise KeyError, "Private key not available — cannot sign" unless @private_key
+
+        @ml_dsa.sign(data, @private_key)
+      end
+
+      # Verify a signature using the public key.
+      def verify(data, signature)
+        @ml_dsa.verify(data, signature, @public_key)
+      end
+
+      # Whether this key can be used for signing.
+      def private?
+        !@private_key.nil?
+      end
+
+      # Import a Key from a PEM string (SPKI or PKCS#8).
+      def self.from_pem(pem_string)
+        info = PqcAsn1::DER.parse_pem(pem_string)
+        alg_name = resolve_oid!(info.oid)
+
+        case info.format
+        when :spki  then new(algorithm: alg_name, public_key: info.key)
+        when :pkcs8 then build_from_pkcs8(info, alg_name)
+        else raise KeyError, "Unsupported PEM format: #{info.format}"
+        end
+      ensure
+        info&.key&.wipe! if info&.format == :pkcs8
+      end
+
+      # Import a Key from separate public and private PEM strings.
+      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)
+
+        pub_alg = OID_TO_ALGORITHM[pub_info.oid]
+        priv_alg = OID_TO_ALGORITHM[priv_info.oid]
+
+        raise KeyError, "Unknown OID in public PEM: #{pub_info.oid.dotted}" unless pub_alg
+        raise KeyError, "Unknown OID in private PEM: #{priv_info.oid.dotted}" unless priv_alg
+        raise KeyError, "Algorithm mismatch: public=#{pub_alg}, private=#{priv_alg}" unless pub_alg == priv_alg
+
+        sk_bytes = extract_secure_bytes(priv_info.key)
+        new(algorithm: pub_alg, public_key: pub_info.key, private_key: sk_bytes)
+      ensure
+        priv_info&.key&.wipe!
+      end
+
+      # Export the public key as PEM (SPKI format).
+      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).
+      def private_to_pem
+        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
+      end
+
+      def self.resolve_algorithm(algorithm)
+        ALGORITHM_ALIASES.fetch(algorithm.to_sym) { algorithm.to_s }
+      end
+
+      # 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.
+      # bytes.bytes.pack creates a fully independent copy via integer array.
+      def self.extract_secure_bytes(secure_buffer)
+        secure_buffer.use { |bytes| bytes.bytes.pack("C*") }
+      end
+
+      def self.resolve_oid!(oid)
+        OID_TO_ALGORITHM[oid] || raise(KeyError, "Unknown OID in PEM: #{oid.dotted}")
+      end
+
+      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
+
+        sk_bytes = extract_secure_bytes(info.key)
+        new(algorithm: alg_name, public_key: info.public_key, private_key: sk_bytes)
+      end
+
+      private_class_method :extract_secure_bytes, :resolve_oid!, :build_from_pkcs8
+
+      private
+
+      def resolve_algorithm(algorithm)
+        self.class.resolve_algorithm(algorithm)
+      end
+
+      def validate!
+        expected_pk = @ml_dsa.public_key_size
+        if @public_key.bytesize != expected_pk
+          raise KeyError,
+                "Invalid public key size for #{@algorithm}: " \
+                "expected #{expected_pk}, got #{@public_key.bytesize}"
+        end
+
+        return unless @private_key
+
+        expected_sk = @ml_dsa.secret_key_size
+        return if @private_key.bytesize == expected_sk
+
+        raise KeyError,
+              "Invalid private key size for #{@algorithm}: " \
+              "expected #{expected_sk}, got #{@private_key.bytesize}"
+      end
+    end
+  end
+end

data/lib/jwt/pq/liboqs.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module JWT
+  module PQ
+    # FFI bindings for liboqs signature operations.
+    #
+    # The library search order:
+    #   1. OQS_LIB environment variable (explicit path)
+    #   2. System-installed liboqs (via standard library search)
+    module LibOQS
+      extend FFI::Library
+
+      OQS_SUCCESS = 0
+      OQS_ERROR = -1
+
+      # Determine library path
+      def self.lib_path
+        return ENV["OQS_LIB"] if ENV["OQS_LIB"]
+
+        "oqs"
+      end
+
+      begin
+        ffi_lib lib_path
+      rescue LoadError => e
+        raise JWT::PQ::LiboqsError,
+              "liboqs not found. Install it via: brew install liboqs (macOS) or " \
+              "apt install liboqs-dev (Ubuntu). You can also set OQS_LIB to the " \
+              "full path of the shared library. Original error: #{e.message}"
+      end
+
+      # OQS_SIG *OQS_SIG_new(const char *method_name)
+      attach_function :OQS_SIG_new, [:string], :pointer
+
+      # void OQS_SIG_free(OQS_SIG *sig)
+      attach_function :OQS_SIG_free, [:pointer], :void
+
+      # OQS_STATUS OQS_SIG_keypair(const OQS_SIG *sig, uint8_t *public_key, uint8_t *secret_key)
+      attach_function :OQS_SIG_keypair, %i[pointer pointer pointer], :int
+
+      # OQS_STATUS OQS_SIG_sign(const OQS_SIG *sig, uint8_t *signature, size_t *signature_len,
+      #                          const uint8_t *message, size_t message_len,
+      #                          const uint8_t *secret_key)
+      attach_function :OQS_SIG_sign, %i[pointer pointer pointer
+                                        pointer size_t pointer], :int
+
+      # OQS_STATUS OQS_SIG_verify(const OQS_SIG *sig, const uint8_t *message,
+      #                            size_t message_len, const uint8_t *signature,
+      #                            size_t signature_len, const uint8_t *public_key)
+      attach_function :OQS_SIG_verify, %i[pointer pointer size_t
+                                          pointer size_t pointer], :int
+    end
+  end
+end

data/lib/jwt/pq/ml_dsa.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module JWT
+  module PQ
+    # Ruby wrapper around liboqs ML-DSA operations.
+    # Handles memory allocation, FFI calls, and cleanup.
+    class MlDsa
+      ALGORITHMS = {
+        "ML-DSA-44" => { public_key: 1312, secret_key: 2560, signature: 2420, nist_level: 2 },
+        "ML-DSA-65" => { public_key: 1952, secret_key: 4032, signature: 3309, nist_level: 3 },
+        "ML-DSA-87" => { public_key: 2592, secret_key: 4896, signature: 4627, nist_level: 5 }
+      }.freeze
+
+      attr_reader :algorithm
+
+      def initialize(algorithm)
+        algorithm = algorithm.to_s
+        unless ALGORITHMS.key?(algorithm)
+          raise UnsupportedAlgorithmError,
+                "Unsupported algorithm: #{algorithm}. " \
+                "Supported: #{ALGORITHMS.keys.join(", ")}"
+        end
+
+        @algorithm = algorithm
+        @sizes = ALGORITHMS[algorithm]
+      end
+
+      # Generate a new keypair.
+      # Returns [public_key_bytes, secret_key_bytes]
+      def keypair
+        sig = LibOQS.OQS_SIG_new(@algorithm)
+        raise LiboqsError, "Failed to initialize #{@algorithm}" if sig.null?
+
+        pk = FFI::MemoryPointer.new(:uint8, @sizes[:public_key])
+        sk = FFI::MemoryPointer.new(:uint8, @sizes[:secret_key])
+
+        status = LibOQS.OQS_SIG_keypair(sig, pk, sk)
+        raise LiboqsError, "Keypair generation failed for #{@algorithm}" unless status == LibOQS::OQS_SUCCESS
+
+        [pk.read_bytes(@sizes[:public_key]), sk.read_bytes(@sizes[:secret_key])]
+      ensure
+        LibOQS.OQS_SIG_free(sig) if sig && !sig.null?
+      end
+
+      # Sign a message with a secret key.
+      # Returns the signature bytes.
+      def sign(message, secret_key)
+        validate_key_size!(secret_key, :secret_key)
+
+        sig = LibOQS.OQS_SIG_new(@algorithm)
+        raise LiboqsError, "Failed to initialize #{@algorithm}" if sig.null?
+
+        sig_buf = FFI::MemoryPointer.new(:uint8, @sizes[:signature])
+        sig_len = FFI::MemoryPointer.new(:size_t)
+        msg_buf = FFI::MemoryPointer.from_string(message)
+        sk_buf = FFI::MemoryPointer.new(:uint8, secret_key.bytesize)
+        sk_buf.put_bytes(0, secret_key)
+
+        status = LibOQS.OQS_SIG_sign(sig, sig_buf, sig_len,
+                                     msg_buf, message.bytesize, sk_buf)
+        raise SignatureError, "Signing failed for #{@algorithm}" unless status == LibOQS::OQS_SUCCESS
+
+        actual_len = sig_len.read(:size_t)
+        sig_buf.read_bytes(actual_len)
+      ensure
+        LibOQS.OQS_SIG_free(sig) if sig && !sig.null?
+      end
+
+      # Verify a signature against a message and public key.
+      # Returns true if valid, false otherwise.
+      def verify(message, signature, public_key)
+        validate_key_size!(public_key, :public_key)
+
+        sig = LibOQS.OQS_SIG_new(@algorithm)
+        raise LiboqsError, "Failed to initialize #{@algorithm}" if sig.null?
+
+        msg_buf = FFI::MemoryPointer.from_string(message)
+        sig_buf = FFI::MemoryPointer.new(:uint8, signature.bytesize)
+        sig_buf.put_bytes(0, signature)
+        pk_buf = FFI::MemoryPointer.new(:uint8, public_key.bytesize)
+        pk_buf.put_bytes(0, public_key)
+
+        status = LibOQS.OQS_SIG_verify(sig, msg_buf, message.bytesize,
+                                       sig_buf, signature.bytesize, pk_buf)
+        status == LibOQS::OQS_SUCCESS
+      ensure
+        LibOQS.OQS_SIG_free(sig) if sig && !sig.null?
+      end
+
+      # Key sizes for this algorithm
+      def public_key_size
+        @sizes[:public_key]
+      end
+
+      def secret_key_size
+        @sizes[:secret_key]
+      end
+
+      def signature_size
+        @sizes[:signature]
+      end
+
+      private
+
+      def validate_key_size!(key, type)
+        expected = @sizes[type]
+        return if key.bytesize == expected
+
+        raise KeyError,
+              "Invalid #{type} size for #{@algorithm}: " \
+              "expected #{expected} bytes, got #{key.bytesize}"
+      end
+    end
+  end
+end

data/lib/jwt/pq/version.rb

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

data/lib/jwt/pq.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "pq/version"
+require_relative "pq/errors"
+require_relative "pq/liboqs"
+require_relative "pq/ml_dsa"
+require_relative "pq/key"
+require_relative "pq/algorithms/ml_dsa"
+require_relative "pq/jwk"
+require_relative "pq/hybrid_key"
+require_relative "pq/algorithms/hybrid_eddsa"
+
+module JWT
+  module PQ
+    # Whether jwt-eddsa / ed25519 is available for hybrid mode.
+    def self.hybrid_available?
+      require "ed25519"
+      true
+    rescue LoadError
+      false
+    end
+  end
+end

metadata

@@ -0,0 +1,110 @@
+--- !ruby/object:Gem::Specification
+name: jwt-pq
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Marcelo Almeida
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pqc_asn1
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+description: Adds ML-DSA-44, ML-DSA-65, and ML-DSA-87 post-quantum signature algorithms
+  to the ruby-jwt ecosystem, with optional hybrid EdDSA + ML-DSA mode. Uses liboqs
+  via FFI.
+email:
+- contact@marcelopazzo.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- jwt-pq.gemspec
+- lib/jwt/pq.rb
+- lib/jwt/pq/algorithms/hybrid_eddsa.rb
+- lib/jwt/pq/algorithms/ml_dsa.rb
+- lib/jwt/pq/errors.rb
+- lib/jwt/pq/hybrid_key.rb
+- lib/jwt/pq/jwk.rb
+- lib/jwt/pq/key.rb
+- lib/jwt/pq/liboqs.rb
+- lib/jwt/pq/ml_dsa.rb
+- lib/jwt/pq/version.rb
+homepage: https://github.com/marcelopazzo/jwt-pq
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/marcelopazzo/jwt-pq
+  changelog_uri: https://github.com/marcelopazzo/jwt-pq/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/marcelopazzo/jwt-pq/issues
+  documentation_uri: https://rubydoc.info/gems/jwt-pq
+  rubygems_mfa_required: 'true'
+post_install_message: |
+  jwt-pq requires liboqs (shared library) to be installed on your system.
+  See https://github.com/marcelopazzo/jwt-pq#installing-liboqs for instructions.
+  For hybrid EdDSA+ML-DSA mode, also add 'jwt-eddsa' to your Gemfile.
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- liboqs >= 0.15.0 (shared library) — https://github.com/open-quantum-safe/liboqs
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Post-quantum JWT signatures (ML-DSA / FIPS 204) for Ruby
+test_files: []