jwt-pq 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50b794a7ae8858987b6ec5608deef2c56e1e7ae89dca00da9e8cfbea14999f06
-  data.tar.gz: a2c66e4bca2430f9f443dcef4d2c8d6a92ce619576ae4c99f1fa61ddef7935aa
+  metadata.gz: 9fc1d22df85af9d7c753800dbd77e08ce874d7c1bf177aa9afafab54a3ef6aa9
+  data.tar.gz: 3f8d5ef4114c28e79eeb609eac5bcff0b5e5bbe0b4869006b20e1e076cf7142f
 SHA512:
-  metadata.gz: ffb6709911168e143e1babc9d1c2209ab5ceaed573529b801f72ba1d20f13cd26575b8c6db6c754e2028c7e695fe492b5ce052fd5b6b002fa5ee7d530f0ea479
-  data.tar.gz: a2f9e6837f2995d09c67576ab317358cbf32b23349416c127c2d11bbbeb91c5ea81d9c914e6f302bb23bf874cd1cd48714af903d9b663f7e4dea62bb04b135d8
+  metadata.gz: 333d7706c667a66e7858813a4de3b813d46c097b283822ed228f3fa23bd5a58fe67dfd0b2cc3a0b7a3e71aceac70ff604c3d8084871828585ce633beba6f7199
+  data.tar.gz: d4ba329c764b33f0aea5dd37f10d0c9eb9623eb34d999bc003382096a18c58e2b914ad51fdd7e472b0e400a5504690acb21744a922944ded0b67cb5ee9bf9e70

data/CHANGELOG.md

@@ -5,6 +5,63 @@ 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).
 
+## [Unreleased]
+
+## [0.3.0] - 2026-04-19
+
+### Added
+
+- Sign-throughput benchmark at `bench/sign_throughput.rb` with a fixed PEM key fixture (`bench/fixtures/ml_dsa_65_sk.pem`), driven by `benchmark-ips`
+- Verify-throughput benchmark at `bench/verify_throughput.rb`
+- NIST ACVP sigVer KAT tests at `spec/jwt/pq/kat_spec.rb` — external interface, pure ML-DSA, empty context; covers ML-DSA-44, ML-DSA-65, and ML-DSA-87 with both passing and known-bad signatures as a canonical correctness gate
+- `JWT::PQ::MlDsa#sign_with_sk_buffer` and `#verify_with_pk_buffer` — fast paths that accept pre-populated FFI buffers. The existing bytes-in `#sign` / `#verify` APIs are unchanged
+
+### Changed
+
+- **ML-DSA signing throughput: +2.6%** (from 6676 to 6849 sigs/s on Ruby 3.4.6 + liboqs 0.15.0 for ML-DSA-65). Class-level cache of the `OQS_SIG` handle per algorithm avoids `OQS_SIG_new`/`OQS_SIG_free` per call; per-`Key` memoization of the secret-key FFI buffer avoids a 4032-byte allocation + copy per sign
+- **ML-DSA verification throughput: +19.4%** (from 7995 to 9548 verifies/s on the same setup for ML-DSA-65). Class-level cache of the `OQS_SIG` handle for verify; per-`Key` memoization of the public-key FFI buffer; inlined type-check in the JWA verify entry point. `Key#verify` now reaches 93% of the raw `OQS_SIG_verify` ceiling; remaining overhead lives inside `ruby-jwt`
+- `Key#destroy!` now also zeroes the cached secret-key FFI buffer (`@sk_buffer`) in addition to `@private_key`, preserving the secure-erase contract after the buffer memoization
+
+### Dependencies
+
+- Add `benchmark-ips ~> 2.14` as a development/test dependency (powers the bench harnesses)
+- Bump `ruby/setup-ruby` from 1.299.0 to 1.301.0 (#2)
+
+## [0.2.0] - 2026-04-06
+
+### Added
+
+- Vendored liboqs build — `gem install jwt-pq` now compiles liboqs from source automatically
+- `Key#destroy!` and `HybridKey#destroy!` for explicit zeroization of private key material
+- `--use-system-libraries` escape hatch for users with pre-installed liboqs
+- `JWT_PQ_LIBOQS_SOURCE` env var for air-gapped environments
+- Path traversal protection in tarball extraction (defense-in-depth)
+- Smoke test job in CI (builds gem, installs, runs end-to-end verification)
+- Weekly CI schedule to catch dependency breakage
+- Dependabot for automated dependency updates
+- Secret scanning and push protection
+- Code coverage with SimpleCov and Codecov
+
+### Changed
+
+- CMake and a C compiler (gcc/clang) are now required at install time
+- `Key#inspect` and `HybridKey#inspect` no longer expose private key material
+- `Key.resolve_algorithm` is now a private class method
+- `JWK::ALGORITHMS` derived from `MlDsa::ALGORITHMS` (single source of truth)
+- Pin CI actions to commit SHAs for security
+- Use `Net::HTTP` instead of `URI.open` for tarball download
+- Restrict CI workflow GITHUB_TOKEN permissions to `contents: read`
+
+### Fixed
+
+- ML-DSA verify with invalid key type now raises `DecodeError` instead of `EncodeError`
+- JWK import now validates missing `pub` field and malformed base64url input
+- FFI memory holding secret keys is now zeroed after use
+
+### Dependencies
+
+- Bump codecov/codecov-action from 5.5.4 to 6.0.0
+
 ## [0.1.0] - 2026-04-04
 
 ### Added
@@ -18,3 +75,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Concatenated signature format: Ed25519 (64B) || ML-DSA
   - Optional dependency on jwt-eddsa / ed25519
 - Error classes: `LiboqsError`, `KeyError`, `SignatureError`, `MissingDependencyError`
+
+[Unreleased]: https://github.com/marcelopazzo/jwt-pq/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/marcelopazzo/jwt-pq/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/marcelopazzo/jwt-pq/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/marcelopazzo/jwt-pq/releases/tag/v0.1.0

data/Gemfile

@@ -5,6 +5,8 @@ source "https://rubygems.org"
 gemspec
 
 group :development, :test do
+  gem "benchmark-ips", "~> 2.14"
+  gem "rake"
   gem "rspec", "~> 3.13"
   gem "rubocop", "~> 1.75"
   gem "rubocop-rspec", "~> 3.0"
@@ -13,4 +15,5 @@ end
 group :test do
   gem "jwt-eddsa", "~> 0.9"
   gem "simplecov", require: false
+  gem "simplecov-cobertura", require: false
 end

data/README.md

@@ -1,5 +1,9 @@
 # jwt-pq
 
+[![Gem Version](https://badge.fury.io/rb/jwt-pq.svg)](https://rubygems.org/gems/jwt-pq)
+[![CI](https://github.com/marcelopazzo/jwt-pq/actions/workflows/ci.yml/badge.svg)](https://github.com/marcelopazzo/jwt-pq/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/marcelopazzo/jwt-pq/graph/badge.svg)](https://codecov.io/gh/marcelopazzo/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
@@ -13,27 +17,7 @@ Post-quantum JWT signatures for Ruby. Adds **ML-DSA** (FIPS 204) support to the
 ## 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.
+- CMake >= 3.15 and a C compiler — gcc or clang (for building the bundled liboqs)
 
 ## Installation
 
@@ -45,6 +29,22 @@ gem "jwt-pq"
 gem "jwt-eddsa"
 ```
 
+liboqs is automatically compiled from source during gem installation (ML-DSA algorithms only, ~30 seconds).
+
+### Using system liboqs
+
+If you prefer to use a system-installed liboqs:
+
+```bash
+gem install jwt-pq -- --use-system-libraries
+# or
+JWT_PQ_USE_SYSTEM_LIBRARIES=1 gem install jwt-pq
+# or in Bundler
+bundle config build.jwt-pq --use-system-libraries
+```
+
+You can also point to a specific library with `OQS_LIB=/path/to/liboqs.dylib`.
+
 ## Usage
 
 ### Basic ML-DSA signing
@@ -133,9 +133,10 @@ The `alg` header values follow a `ClassicAlg+PQAlg` convention. The IETF draft `
 ## Development
 
 ```bash
-bundle install
-OQS_LIB=/path/to/liboqs.dylib bundle exec rspec
-bundle exec rubocop
+bundle install          # compiles liboqs automatically
+bundle exec rspec       # run tests
+bundle exec rubocop     # lint
+rake compile            # recompile liboqs manually
 ```
 
 ## License

data/Rakefile

@@ -5,4 +5,12 @@ require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 
+desc "Compile the liboqs extension"
+task :compile do
+  Dir.chdir("ext/jwt/pq") do
+    ruby "extconf.rb"
+    sh "make"
+  end
+end
+
 task default: :spec

data/bench/fixtures/ml_dsa_65_sk.pem

@@ -0,0 +1,128 @@
+-----BEGIN PRIVATE KEY-----
+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
+aEqLBCQtoXub0y7W
+-----END PRIVATE KEY-----

data/bench/sign_throughput.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "jwt"
+require "jwt/pq"
+
+ALG = "ML-DSA-65"
+PAYLOAD = { sub: "user-123", iat: 1_700_000_000, exp: 1_700_003_600 }.freeze
+FIXTURE = File.expand_path("fixtures/ml_dsa_65_sk.pem", __dir__)
+
+abort "Missing bench fixture: #{FIXTURE}" unless File.exist?(FIXTURE)
+key = JWT::PQ::Key.from_pem(File.read(FIXTURE))
+
+100.times { JWT.encode(PAYLOAD, key, ALG) }
+
+report = Benchmark.ips(quiet: true) do |x|
+  x.config(time: 5, warmup: 2)
+  x.report("sign") { JWT.encode(PAYLOAD, key, ALG) }
+end
+
+entry = report.entries.first
+ips = entry.stats.central_tendency
+us_per_op = 1_000_000.0 / ips
+
+puts "METRIC sigs_per_sec=#{ips.round(2)}"
+puts "METRIC us_per_sig=#{us_per_op.round(2)}"

data/bench/verify_throughput.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "benchmark/ips"
+require "jwt"
+require "jwt/pq"
+
+ALG = "ML-DSA-65"
+PAYLOAD = { sub: "user-123", iat: 1_700_000_000, exp: 1_700_003_600 }.freeze
+FIXTURE = File.expand_path("fixtures/ml_dsa_65_sk.pem", __dir__)
+
+abort "Missing bench fixture: #{FIXTURE}" unless File.exist?(FIXTURE)
+key = JWT::PQ::Key.from_pem(File.read(FIXTURE))
+pub_key = JWT::PQ::Key.from_public_key(ALG, key.public_key)
+
+TOKEN = JWT.encode(PAYLOAD, key, ALG)
+
+100.times { JWT.decode(TOKEN, pub_key, true, algorithms: [ALG], verify_expiration: false) }
+
+report = Benchmark.ips(quiet: true) do |x|
+  x.config(time: 5, warmup: 2)
+  x.report("verify") { JWT.decode(TOKEN, pub_key, true, algorithms: [ALG], verify_expiration: false) }
+end
+
+entry = report.entries.first
+ips = entry.stats.central_tendency
+us_per_op = 1_000_000.0 / ips
+
+puts "METRIC verifies_per_sec=#{ips.round(2)}"
+puts "METRIC us_per_verify=#{us_per_op.round(2)}"

data/bin/smoke.rb

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "jwt/pq"
+
+puts "jwt-pq v#{JWT::PQ::VERSION} smoke test"
+
+# ML-DSA-65 sign/verify round-trip
+key = JWT::PQ::Key.generate(:ml_dsa_65)
+token = JWT.encode({ "sub" => "smoke-test" }, key, "ML-DSA-65")
+decoded = JWT.decode(token, key, true, algorithms: ["ML-DSA-65"])
+
+raise "Decode failed" unless decoded.first["sub"] == "smoke-test"
+
+puts "ML-DSA-65 sign/verify: OK"
+
+# PEM round-trip
+pub_pem = key.to_pem
+restored = JWT::PQ::Key.from_pem(pub_pem)
+decoded = JWT.decode(token, restored, true, algorithms: ["ML-DSA-65"])
+
+raise "PEM round-trip failed" unless decoded.first["sub"] == "smoke-test"
+
+puts "PEM round-trip: OK"
+
+# JWK round-trip
+jwk = JWT::PQ::JWK.new(key)
+imported = JWT::PQ::JWK.import(jwk.export)
+decoded = JWT.decode(token, imported, true, algorithms: ["ML-DSA-65"])
+
+raise "JWK round-trip failed" unless decoded.first["sub"] == "smoke-test"
+
+puts "JWK round-trip: OK"
+
+# Key destroy
+key.destroy!
+raise "destroy! failed" if key.private?
+
+puts "Key#destroy!: OK"
+puts "All smoke tests passed"

data/ext/jwt/pq/extconf.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "fileutils"
+require "net/http"
+require "uri"
+require "digest"
+require "rubygems/package"
+require "zlib"
+require "etc"
+require "tmpdir"
+
+LIBOQS_VERSION = "0.15.0"
+LIBOQS_SHA256 = "3983f7cd1247f37fb76a040e6fd684894d44a84cecdcfbdb90559b3216684b5c"
+LIBOQS_URL = "https://github.com/open-quantum-safe/liboqs/archive/refs/tags/#{LIBOQS_VERSION}.tar.gz"
+
+PACKAGE_ROOT_DIR = File.expand_path("../../..", __dir__)
+VENDOR_DIR = File.join(PACKAGE_ROOT_DIR, "lib", "jwt", "pq", "vendor")
+
+def write_dummy_makefile
+  File.write("Makefile", <<~MAKEFILE)
+    all:
+    \t@echo "jwt-pq: nothing to compile"
+    install:
+    \t@echo "jwt-pq: nothing to install"
+    clean:
+    \t@echo "jwt-pq: nothing to clean"
+  MAKEFILE
+end
+
+def use_system_libraries?
+  ENV.key?("JWT_PQ_USE_SYSTEM_LIBRARIES") ||
+    enable_config("system-libraries", false)
+end
+
+def check_cmake!
+  cmake = find_executable("cmake")
+  unless cmake
+    abort <<~MSG
+      ERROR: cmake is required to compile liboqs for jwt-pq.
+
+      Install it with:
+        macOS:  brew install cmake
+        Ubuntu: sudo apt-get install cmake
+
+      Alternatively, install liboqs manually and use:
+        gem install jwt-pq -- --use-system-libraries
+    MSG
+  end
+  cmake
+end
+
+def download_via_http(url, dest_path, redirect_limit = 5)
+  abort "ERROR: too many redirects downloading liboqs" if redirect_limit.zero?
+
+  uri = URI.parse(url)
+  response = Net::HTTP.get_response(uri)
+
+  case response
+  when Net::HTTPSuccess
+    File.binwrite(dest_path, response.body)
+  when Net::HTTPRedirection
+    download_via_http(response["location"], dest_path, redirect_limit - 1)
+  else
+    abort "ERROR: failed to download liboqs (HTTP #{response.code}): #{uri}"
+  end
+end
+
+def download_source(dest_dir)
+  tarball_path = File.join(dest_dir, "liboqs-#{LIBOQS_VERSION}.tar.gz")
+
+  # Support local tarball via env var (for air-gapped environments)
+  source = ENV.fetch("JWT_PQ_LIBOQS_SOURCE", LIBOQS_URL)
+
+  $stdout.puts "jwt-pq: downloading liboqs #{LIBOQS_VERSION}..."
+  if source.start_with?("http")
+    download_via_http(source, tarball_path)
+  else
+    FileUtils.cp(source, tarball_path)
+  end
+
+  # Verify checksum
+  actual = Digest::SHA256.file(tarball_path).hexdigest
+  unless actual == LIBOQS_SHA256
+    abort "ERROR: SHA-256 mismatch for liboqs tarball.\n" \
+          "  Expected: #{LIBOQS_SHA256}\n" \
+          "  Got:      #{actual}"
+  end
+
+  tarball_path
+end
+
+def extract_tarball(tarball_path, dest_dir)
+  $stdout.puts "jwt-pq: extracting liboqs #{LIBOQS_VERSION}..."
+  File.open(tarball_path, "rb") do |file|
+    Zlib::GzipReader.wrap(file) do |gz|
+      Gem::Package::TarReader.new(gz) do |tar|
+        tar.each do |entry|
+          dest = File.expand_path(File.join(dest_dir, entry.full_name))
+          unless dest.start_with?("#{File.expand_path(dest_dir)}/")
+            abort "ERROR: path traversal detected in tarball: #{entry.full_name}"
+          end
+
+          if entry.directory?
+            FileUtils.mkdir_p(dest)
+          elsif entry.file?
+            FileUtils.mkdir_p(File.dirname(dest))
+            File.binwrite(dest, entry.read)
+            File.chmod(entry.header.mode, dest) if entry.header.mode && entry.header.mode > 0
+          end
+        end
+      end
+    end
+  end
+
+  File.join(dest_dir, "liboqs-#{LIBOQS_VERSION}")
+end
+
+def build_liboqs(source_dir)
+  build_dir = File.join(source_dir, "build")
+  FileUtils.mkdir_p(build_dir)
+  FileUtils.mkdir_p(VENDOR_DIR)
+
+  nproc = begin
+    Etc.nprocessors
+  rescue StandardError
+    2
+  end
+
+  # Semicolons are cmake list separators (safe here — system() uses execvp, no shell)
+  cmake_args = %W[
+    -DBUILD_SHARED_LIBS=ON
+    -DOQS_MINIMAL_BUILD=SIG_ml_dsa_44;SIG_ml_dsa_65;SIG_ml_dsa_87
+    -DOQS_BUILD_ONLY_LIB=ON
+    -DOQS_USE_OPENSSL=OFF
+    -DCMAKE_BUILD_TYPE=Release
+    -DCMAKE_INSTALL_PREFIX=#{VENDOR_DIR}
+    -DCMAKE_POSITION_INDEPENDENT_CODE=ON
+  ]
+
+  # Use Ninja if available (faster), fall back to Make
+  if find_executable("ninja")
+    cmake_args << "-GNinja"
+  end
+
+  $stdout.puts "jwt-pq: configuring liboqs #{LIBOQS_VERSION} (ML-DSA only)..."
+  unless system("cmake", "-S", source_dir, "-B", build_dir, *cmake_args)
+    abort "ERROR: cmake configure failed for liboqs"
+  end
+
+  $stdout.puts "jwt-pq: compiling liboqs (using #{nproc} cores)..."
+  unless system("cmake", "--build", build_dir, "--parallel", nproc.to_s)
+    abort "ERROR: cmake build failed for liboqs"
+  end
+
+  $stdout.puts "jwt-pq: installing liboqs to vendor directory..."
+  unless system("cmake", "--install", build_dir)
+    abort "ERROR: cmake install failed for liboqs"
+  end
+end
+
+def find_vendored_library
+  %w[dylib so].each do |ext|
+    path = File.join(VENDOR_DIR, "lib", "liboqs.#{ext}")
+    return path if File.exist?(path)
+  end
+  nil
+end
+
+# --- Main ---
+
+if use_system_libraries?
+  $stdout.puts "jwt-pq: using system liboqs (--use-system-libraries)"
+  write_dummy_makefile
+  exit 0
+end
+
+check_cmake!
+
+Dir.mktmpdir("jwt-pq-build") do |tmp_dir|
+  tarball = download_source(tmp_dir)
+  source_dir = extract_tarball(tarball, tmp_dir)
+  build_liboqs(source_dir)
+end
+
+lib_path = find_vendored_library
+if lib_path
+  $stdout.puts "jwt-pq: liboqs #{LIBOQS_VERSION} installed at #{lib_path}"
+else
+  abort "ERROR: liboqs shared library not found after build"
+end
+
+write_dummy_makefile

data/jwt-pq.gemspec

@@ -24,12 +24,14 @@ Gem::Specification.new do |spec|
     "rubygems_mfa_required" => "true"
   }
 
-  spec.requirements = ["liboqs >= 0.15.0 (shared library) — https://github.com/open-quantum-safe/liboqs"]
+  spec.requirements = ["cmake >= 3.15", "C compiler (gcc or clang)"]
 
   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.
+    jwt-pq compiles liboqs from source during installation.
+    If the build failed, ensure cmake and a C compiler are installed.
+    To use a system-installed liboqs instead:
+      gem install jwt-pq -- --use-system-libraries
+    For hybrid EdDSA+ML-DSA mode, add 'jwt-eddsa' to your Gemfile.
   MSG
 
   spec.files = Dir.chdir(__dir__) do
@@ -39,6 +41,7 @@ Gem::Specification.new do |spec|
     end
   end
 
+  spec.extensions = ["ext/jwt/pq/extconf.rb"]
   spec.require_paths = ["lib"]
 
   spec.add_dependency "ffi", "~> 1.15"

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

@@ -15,23 +15,28 @@ module JWT
         end
 
         def sign(data:, signing_key:)
-          key = resolve_key(signing_key)
-          raise_sign_error!("Private key required for signing") unless key.private?
+          key = resolve_signing_key(signing_key)
           key.sign(data)
         end
 
         def verify(data:, signature:, verification_key:)
-          key = resolve_key(verification_key)
-          key.verify(data, signature)
+          unless verification_key.is_a?(JWT::PQ::Key)
+            raise_verify_error!(
+              "Expected a JWT::PQ::Key, got #{verification_key.class}. " \
+              "Use JWT::PQ::Key.generate(:#{alg_symbol}) to create a key."
+            )
+          end
+          verification_key.verify(data, signature)
         rescue JWT::PQ::Error
           false
         end
 
         private
 
-        def resolve_key(key)
+        def resolve_signing_key(key)
           case key
           when JWT::PQ::Key
+            raise_sign_error!("Private key required for signing") unless key.private?
             key
           else
             raise_sign_error!(
@@ -41,6 +46,18 @@ module JWT
           end
         end
 
+        def resolve_verification_key(key)
+          case key
+          when JWT::PQ::Key
+            key
+          else
+            raise_verify_error!(
+              "Expected a JWT::PQ::Key, got #{key.class}. " \
+              "Use JWT::PQ::Key.generate(:#{alg_symbol}) to create a key."
+            )
+          end
+        end
+
         def alg_symbol
           alg.downcase.tr("-", "_")
         end

data/lib/jwt/pq/hybrid_key.rb

@@ -51,6 +51,23 @@ module JWT
         "EdDSA+#{@ml_dsa_key.algorithm}"
       end
 
+      # Zero and discard private key material from both key components.
+      # After calling this, the key can only be used for verification.
+      def destroy!
+        @ml_dsa_key.destroy!
+        if @ed25519_signing_key
+          seed = @ed25519_signing_key.to_bytes
+          seed.replace("\0" * seed.bytesize)
+          @ed25519_signing_key = nil
+        end
+        true
+      end
+
+      def inspect
+        "#<#{self.class} algorithm=#{hybrid_algorithm} private=#{private?}>"
+      end
+      alias to_s inspect
+
       def self.require_eddsa_dependency!
         require "ed25519"
       rescue LoadError

data/lib/jwt/pq/jwk.rb

@@ -13,7 +13,7 @@ module JWT
     #   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
+      ALGORITHMS = MlDsa::ALGORITHMS.keys.freeze
       KTY = "AKP"
 
       attr_reader :key
@@ -44,10 +44,12 @@ module JWT
 
         validate_kty!(jwk)
         alg = validate_alg!(jwk)
-        pub_bytes = base64url_decode(jwk["pub"])
+        raise KeyError, "Missing 'pub' in JWK" unless jwk.key?("pub")
+
+        pub_bytes = decode_field(jwk, "pub")
 
         if jwk.key?("priv")
-          priv_bytes = base64url_decode(jwk["priv"])
+          priv_bytes = decode_field(jwk, "priv")
           Key.new(algorithm: alg, public_key: pub_bytes, private_key: priv_bytes)
         else
           Key.new(algorithm: alg, public_key: pub_bytes)
@@ -83,10 +85,12 @@ module JWT
       end
       private_class_method :normalize_keys
 
-      def self.base64url_decode(str)
-        ::Base64.urlsafe_decode64(str)
+      def self.decode_field(jwk, field)
+        ::Base64.urlsafe_decode64(jwk[field])
+      rescue ArgumentError => e
+        raise KeyError, "Invalid base64url in JWK '#{field}': #{e.message}"
       end
-      private_class_method :base64url_decode
+      private_class_method :decode_field
 
       private
 

data/lib/jwt/pq/key.rb

@@ -6,7 +6,7 @@ module JWT
   module PQ
     # Represents an ML-DSA keypair (public + optional private key).
     # Used as the signing/verification key for JWT operations.
-    class Key
+    class Key # rubocop:disable Metrics/ClassLength
       ALGORITHM_ALIASES = {
         ml_dsa_44: "ML-DSA-44",
         ml_dsa_65: "ML-DSA-65",
@@ -50,12 +50,12 @@ module JWT
       def sign(data)
         raise KeyError, "Private key not available — cannot sign" unless @private_key
 
-        @ml_dsa.sign(data, @private_key)
+        @ml_dsa.sign_with_sk_buffer(data, sk_buffer)
       end
 
       # Verify a signature using the public key.
       def verify(data, signature)
-        @ml_dsa.verify(data, signature, @public_key)
+        @ml_dsa.verify_with_pk_buffer(data, signature, pk_buffer)
       end
 
       # Whether this key can be used for signing.
@@ -63,6 +63,23 @@ module JWT
         !@private_key.nil?
       end
 
+      # Zero and discard private key material from Ruby memory.
+      # After calling this, the key can only be used for verification.
+      def destroy!
+        if @private_key
+          @private_key.replace("\0" * @private_key.bytesize)
+          @private_key = nil
+        end
+        @sk_buffer&.clear
+        @sk_buffer = nil
+        true
+      end
+
+      def inspect
+        "#<#{self.class} algorithm=#{@algorithm} private=#{private?}>"
+      end
+      alias to_s inspect
+
       # Import a Key from a PEM string (SPKI or PKCS#8).
       def self.from_pem(pem_string)
         info = PqcAsn1::DER.parse_pem(pem_string)
@@ -134,12 +151,20 @@ module JWT
         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_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
+
+      def pk_buffer
+        @pk_buffer ||= FFI::MemoryPointer.new(:uint8, @public_key.bytesize).put_bytes(0, @public_key)
+      end
+
       def resolve_algorithm(algorithm)
-        self.class.resolve_algorithm(algorithm)
+        self.class.send(:resolve_algorithm, algorithm)
       end
 
       def validate!

data/lib/jwt/pq/liboqs.rb

@@ -6,29 +6,46 @@ module JWT
   module PQ
     # FFI bindings for liboqs signature operations.
     #
-    # The library search order:
+    # Library search order:
     #   1. OQS_LIB environment variable (explicit path)
-    #   2. System-installed liboqs (via standard library search)
+    #   2. Vendored liboqs (compiled during gem install)
+    #   3. 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
+        # 1. Explicit path from environment
         return ENV["OQS_LIB"] if ENV["OQS_LIB"]
 
+        # 2. Vendored library (compiled during gem install)
+        vendored = vendored_lib_path
+        return vendored if vendored
+
+        # 3. System library
         "oqs"
       end
 
+      def self.vendored_lib_path
+        %w[dylib so].each do |ext|
+          path = File.join(__dir__, "vendor", "lib", "liboqs.#{ext}")
+          return path if File.exist?(path)
+        end
+        nil
+      end
+      private_class_method :vendored_lib_path
+
       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}"
+              "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}"
       end
 
       # OQS_SIG *OQS_SIG_new(const char *method_name)

data/lib/jwt/pq/ml_dsa.rb

@@ -11,6 +11,34 @@ module JWT
         "ML-DSA-87" => { public_key: 2592, secret_key: 4896, signature: 4627, nist_level: 5 }
       }.freeze
 
+      @sign_handles = {}
+      @sign_handles_mutex = Mutex.new
+
+      def self.sign_handle(algorithm)
+        @sign_handles[algorithm] || @sign_handles_mutex.synchronize do
+          @sign_handles[algorithm] ||= begin
+            h = LibOQS.OQS_SIG_new(algorithm)
+            raise LiboqsError, "Failed to initialize #{algorithm}" if h.null?
+
+            h
+          end
+        end
+      end
+
+      @verify_handles = {}
+      @verify_handles_mutex = Mutex.new
+
+      def self.verify_handle(algorithm)
+        @verify_handles[algorithm] || @verify_handles_mutex.synchronize do
+          @verify_handles[algorithm] ||= begin
+            h = LibOQS.OQS_SIG_new(algorithm)
+            raise LiboqsError, "Failed to initialize #{algorithm}" if h.null?
+
+            h
+          end
+        end
+      end
+
       attr_reader :algorithm
 
       def initialize(algorithm)
@@ -39,6 +67,7 @@ module JWT
 
         [pk.read_bytes(@sizes[:public_key]), sk.read_bytes(@sizes[:secret_key])]
       ensure
+        sk&.clear
         LibOQS.OQS_SIG_free(sig) if sig && !sig.null?
       end
 
@@ -47,23 +76,28 @@ module JWT
       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?
+        sk_buf = FFI::MemoryPointer.new(:uint8, secret_key.bytesize)
+        sk_buf.put_bytes(0, secret_key)
+        sign_with_sk_buffer(message, sk_buf)
+      ensure
+        sk_buf&.clear
+      end
 
+      # Faster sign path: takes a pre-populated FFI::MemoryPointer holding the
+      # secret key. Caller is responsible for buffer lifecycle (allocation,
+      # zeroing). Used by JWT::PQ::Key to avoid re-allocating+copying the
+      # secret key on every sign call.
+      def sign_with_sk_buffer(message, sk_buf)
+        sig = self.class.sign_handle(@algorithm)
         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?
+        sig_buf.read_bytes(sig_len.read(:size_t))
       end
 
       # Verify a signature against a message and public key.
@@ -71,20 +105,24 @@ module JWT
       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?
+        pk_buf = FFI::MemoryPointer.new(:uint8, public_key.bytesize)
+        pk_buf.put_bytes(0, public_key)
+        verify_with_pk_buffer(message, signature, pk_buf)
+      end
 
+      # Faster verify path: takes a pre-populated FFI::MemoryPointer holding
+      # the public key. Caller is responsible for buffer lifecycle. Used by
+      # JWT::PQ::Key to avoid re-allocating+copying the public key on every
+      # verify call.
+      def verify_with_pk_buffer(message, signature, pk_buf)
+        sig = self.class.verify_handle(@algorithm)
         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

data/lib/jwt/pq/version.rb

@@ -2,6 +2,6 @@
 
 module JWT
   module PQ
-    VERSION = "0.1.0"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jwt-pq
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Marcelo Almeida
@@ -57,7 +57,8 @@ description: Adds ML-DSA-44, ML-DSA-65, and ML-DSA-87 post-quantum signature alg
 email:
 - contact@marcelopazzo.com
 executables: []
-extensions: []
+extensions:
+- ext/jwt/pq/extconf.rb
 extra_rdoc_files: []
 files:
 - CHANGELOG.md
@@ -65,6 +66,11 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- bench/fixtures/ml_dsa_65_sk.pem
+- bench/sign_throughput.rb
+- bench/verify_throughput.rb
+- bin/smoke.rb
+- ext/jwt/pq/extconf.rb
 - jwt-pq.gemspec
 - lib/jwt/pq.rb
 - lib/jwt/pq/algorithms/hybrid_eddsa.rb
@@ -86,9 +92,11 @@ metadata:
   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.
+  jwt-pq compiles liboqs from source during installation.
+  If the build failed, ensure cmake and a C compiler are installed.
+  To use a system-installed liboqs instead:
+    gem install jwt-pq -- --use-system-libraries
+  For hybrid EdDSA+ML-DSA mode, add 'jwt-eddsa' to your Gemfile.
 rdoc_options: []
 require_paths:
 - lib
@@ -103,7 +111,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
-- liboqs >= 0.15.0 (shared library) — https://github.com/open-quantum-safe/liboqs
+- cmake >= 3.15
+- C compiler (gcc or clang)
 rubygems_version: 3.6.9
 specification_version: 4
 summary: Post-quantum JWT signatures (ML-DSA / FIPS 204) for Ruby