linzer 0.7.9 → 0.8.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91f1e3986fae03eb9bf01d4dc8e9c919cd7072ea3ae0f8168099261da0da8c11
-  data.tar.gz: fb07600d19e8e2198e7cbcfb910516d9300e3aa89d94e81e3bc3ebd6a9d007e8
+  metadata.gz: 0330e72cbbfb7cc56b9fa124a4f60a18bb7fbdab4eb98a072598c8fc3680cf76
+  data.tar.gz: 321630c979fc736cc64284eb535b22752e50a42c8bbfae399cbf0db56efecdd3
 SHA512:
-  metadata.gz: aed32987b8ea9fc398ef1d263a94ce3df3ec86e8cd331d2e9b23383c0c6de1db3f0bdaa621990eb1809c210b0ae3f38b045abd2e8e48229a9ec8129cf4213c65
-  data.tar.gz: 26a21c99d8e383af31395f5ebfa5581b0fedf126bb1bb806db3cb1eb0f0d89306dde3af7bf54100cd0251235f54e5cd4f852f8d61007b74fe079716b4447986a
+  metadata.gz: e6e99bf6a409b960d0432f702b286f7b71b06a34b61ff242d2d75eebc9c125bc02c6daa573efc5af69dfeb7c2f788811fb91d2f6f6decd1a869db26e6a5462e6
+  data.tar.gz: 9c76877de5ba5164f677aad7be9ffb3f905f2fd874523b9f2aaff287abd0ebdd8d8c7272da22eddfcacb56a7eb325392e52e1b2a3b551e8940627b146190a895

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 ## [Unreleased]
 
+## [0.8.0.beta1] - 2026-05-07
+
+- Optimize signature parsing, serialization, and validation performance
+  across signing and verifying flows, improving `sign!` throughput by
+  473% and `verify!` by 136% by minimizing Starry usage in hot paths
+  where possible.
+
+- Add comprehensive benchmarking and profiling infrastructure across all
+  supported algorithms.
+
+- Make Rack an optional dependency.
+
 ## [0.7.9] - 2026-04-30
 
 (No changes since the last beta release, this new stable release just

data/README.md

@@ -45,6 +45,8 @@ sections.
 Add the middleware to your Rack application:
 
 ```ruby
+require "linzer/rack"
+
 # config.ru
 use Rack::Auth::Signature,
   except: "/login",
@@ -64,6 +66,8 @@ for all endpoints except /login.
 For more complex setups, you can load configuration from a file, e.g.:
 
 ```ruby
+require "linzer/rack"
+
 # config.ru
 use Rack::Auth::Signature,
   except: "/login",
@@ -75,6 +79,8 @@ use Rack::Auth::Signature,
 In a Rails application, add the middleware in your configuration:
 
 ```ruby
+require "linzer/rack"
+
 # config/application.rb
 config.middleware.use Rack::Auth::Signature,
   except: "/login",
@@ -255,6 +261,8 @@ For production use, prefer a full-featured HTTP client).
 You can sign responses using the same API as for requests, e.g.:
 
 ```ruby
+require "linzer/rack"
+
 put "/baz" do
   ...
   response

data/Rakefile

@@ -12,5 +12,11 @@ task :integration do
   sh "bundle exec rspec -t integration spec/integration/**"
 end
 
+desc "Run benchmarks"
+task :benchmarks do
+  sh "bundle exec ruby benchmarks/sign.rb"
+  sh "bundle exec ruby benchmarks/verify.rb"
+end
+
 task default: %i[spec standard]
 task all: %i[integration default]

data/benchmarks/profile_sign_ed25519.rb

@@ -0,0 +1,102 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Profile: Linzer.sign! with Ed25519 keys
+#
+# Uses StackProf (sampling CPU profiler) to identify bottlenecks in the
+# signing hot path. Produces both a summary report and a flamegraph-ready
+# dump file.
+#
+# Run with:
+#   ruby benchmarks/profile_sign_ed25519.rb
+#
+# For flamegraph (requires stackprof gem):
+#   stackprof --flamegraph tmp/stackprof-sign-ed25519.dump > tmp/flamegraph.json
+#   stackprof --flamegraph-viewer tmp/flamegraph.json
+
+require "bundler/setup"
+require "linzer"
+require "net/http"
+require "stackprof"
+require "fileutils"
+
+ITERATIONS = Integer(ENV.fetch("ITERATIONS", 5_000))
+OUTPUT_DIR = "tmp"
+DUMP_FILE  = File.join(OUTPUT_DIR, "stackprof-sign-ed25519.dump")
+
+FileUtils.mkdir_p(OUTPUT_DIR)
+
+key        = Linzer.generate_ed25519_key("bench-ed25519")
+uri        = URI("https://example.com/api/resource")
+components = %w[@method @path @authority content-type]
+
+puts "StackProf profile \u2014 Linzer.sign! (Ed25519)"
+puts "Ruby #{RUBY_VERSION} / #{RUBY_PLATFORM}"
+puts "Iterations: #{ITERATIONS}"
+puts
+
+# Warm up (JIT, autoloads, caches)
+20.times do
+  req = Net::HTTP::Post.new(uri)
+  req["content-type"] = "application/json"
+  req.body = '{"hello":"world"}'
+  Linzer.sign!(req, key: key, components: components)
+end
+
+StackProf.run(
+  mode:     :cpu,
+  interval: 100,         # sample every 100 \u00b5s
+  out:      DUMP_FILE,
+  raw:      true          # needed for flamegraph output
+) do
+  ITERATIONS.times do
+    request = Net::HTTP::Post.new(uri)
+    request["content-type"] = "application/json"
+    request.body = '{"hello":"world"}'
+
+    Linzer.sign!(request, key: key, components: components)
+  end
+end
+
+puts "=" * 78
+puts "METHOD-LEVEL REPORT (top 30 by self time)"
+puts "=" * 78
+puts
+
+report = StackProf::Report.new(Marshal.load(File.binread(DUMP_FILE)))
+report.print_text(false, 30)
+
+puts
+puts "=" * 78
+puts "METHOD-LEVEL REPORT (top 30 by total time)"
+puts "=" * 78
+puts
+
+report.print_text(true, 30)
+
+# Also print source-annotated hotspots for the top methods
+puts
+puts "=" * 78
+puts "SOURCE ANNOTATIONS FOR TOP METHODS"
+puts "=" * 78
+
+top_frames = report.data[:frames]
+  .sort_by { |_id, f| -(f[:samples] || 0) }
+  .first(10)
+
+top_frames.each do |_frame_id, frame|
+  name = frame[:name]
+  file = frame[:file]
+  next unless file && File.exist?(file)
+  puts
+  puts "-" * 78
+  puts "#{name}  (#{file}:#{frame[:line]})"
+  puts "  self: #{frame[:samples]}  total: #{frame[:total_samples]}"
+  puts "-" * 78
+  report.print_method(name)
+end
+
+puts
+puts "Dump written to: #{DUMP_FILE}"
+puts "To generate a flamegraph:"
+puts "  stackprof --flamegraph #{DUMP_FILE} > tmp/flamegraph.json"

data/benchmarks/profile_verify_ed25519.rb

@@ -0,0 +1,107 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Profile: Linzer.verify! with Ed25519 keys
+#
+# Uses StackProf (sampling CPU profiler) to identify bottlenecks in the
+# verification hot path.
+#
+# Run with:
+#   ruby benchmarks/profile_verify_ed25519.rb
+
+require "bundler/setup"
+require "linzer"
+require "net/http"
+require "stackprof"
+require "fileutils"
+
+ITERATIONS = Integer(ENV.fetch("ITERATIONS", 5_000))
+OUTPUT_DIR = "tmp"
+DUMP_FILE  = File.join(OUTPUT_DIR, "stackprof-verify-ed25519.dump")
+
+FileUtils.mkdir_p(OUTPUT_DIR)
+
+key        = Linzer.generate_ed25519_key("bench-ed25519")
+uri        = URI("https://example.com/api/resource")
+components = %w[@method @path @authority content-type]
+
+# Sign a request once
+request = Net::HTTP::Post.new(uri)
+request["content-type"] = "application/json"
+request.body = '{"hello":"world"}'
+Linzer.sign!(request, key: key, components: components)
+
+sig_header   = request["signature"]
+input_header = request["signature-input"]
+
+puts "StackProf profile \u2014 Linzer.verify! (Ed25519)"
+puts "Ruby #{RUBY_VERSION} / #{RUBY_PLATFORM}"
+puts "Iterations: #{ITERATIONS}"
+puts
+
+# Warm up
+20.times do
+  req = Net::HTTP::Post.new(uri)
+  req["content-type"]    = "application/json"
+  req.body               = '{"hello":"world"}'
+  req["signature"]       = sig_header
+  req["signature-input"] = input_header
+  Linzer.verify!(req, key: key)
+end
+
+StackProf.run(
+  mode:     :cpu,
+  interval: 100,
+  out:      DUMP_FILE,
+  raw:      true
+) do
+  ITERATIONS.times do
+    req = Net::HTTP::Post.new(uri)
+    req["content-type"]    = "application/json"
+    req.body               = '{"hello":"world"}'
+    req["signature"]       = sig_header
+    req["signature-input"] = input_header
+    Linzer.verify!(req, key: key)
+  end
+end
+
+puts "=" * 78
+puts "METHOD-LEVEL REPORT (top 30 by self time)"
+puts "=" * 78
+puts
+
+report = StackProf::Report.new(Marshal.load(File.binread(DUMP_FILE)))
+report.print_text(false, 30)
+
+puts
+puts "=" * 78
+puts "METHOD-LEVEL REPORT (top 30 by total time)"
+puts "=" * 78
+puts
+
+report.print_text(true, 30)
+
+# Source-annotated hotspots for the top methods
+puts
+puts "=" * 78
+puts "SOURCE ANNOTATIONS FOR TOP METHODS"
+puts "=" * 78
+
+top_frames = report.data[:frames]
+  .sort_by { |_id, f| -(f[:samples] || 0) }
+  .first(10)
+
+top_frames.each do |_frame_id, frame|
+  name = frame[:name]
+  file = frame[:file]
+  next unless file && File.exist?(file)
+  puts
+  puts "-" * 78
+  puts "#{name}  (#{file}:#{frame[:line]})"
+  puts "  self: #{frame[:samples]}  total: #{frame[:total_samples]}"
+  puts "-" * 78
+  report.print_method(name)
+end
+
+puts
+puts "Dump written to: #{DUMP_FILE}"

data/benchmarks/sign.rb

@@ -0,0 +1,55 @@
+require "benchmark_driver"
+require "openssl"
+
+BENCH_ALGS = %i[
+  ed25519
+  ecdsa_p256_sha256
+  ecdsa_p384_sha384
+  rsa_v1_5_sha256
+  rsa_pss_sha512
+  hmac_sha256
+  jws_ed25519
+]
+
+puts "Linzer.sign! benchmark — supported algorithms"
+puts `git show HEAD | head -1 | cut -b 1-15`
+puts "Ruby #{RUBY_VERSION} / #{RUBY_PLATFORM}"
+puts "OpenSSL #{OpenSSL::VERSION}"
+puts Time.now.utc
+
+BENCH_ALGS.each do |alg|
+  next if alg == :rsa_pss_sha512 && RUBY_VERSION < "3.1.0"
+  Benchmark.driver do |x|
+    x.prelude <<~RUBY
+      require "bundler/setup"
+      require "linzer"
+      require "linzer/jws"
+
+      def generate_linzer_key(alg)
+        case alg
+        when :ed25519, :ecdsa_p256_sha256, :ecdsa_p384_sha384, :hmac_sha256
+          Linzer.public_send(:"generate_#{alg}_key", "bench-#{alg}")
+        when :rsa_v1_5_sha256, :rsa_pss_sha512
+          Linzer.public_send(:"generate_#{alg}_key", 2048, "bench-#{alg}")
+        when :jws_ed25519
+          Linzer.generate_jws_key(algorithm: "EdDSA")
+        else
+          raise ArgumentError, "Unknown algorithm!"
+        end
+      end
+
+      key = generate_linzer_key(:"#{alg}")
+      uri        = URI("https://example.com/api/resource")
+      components = %w[@method @path @authority content-type]
+    RUBY
+
+    puts "\n#{alg}:\n#{"#" * 70}\n\n"
+
+    x.report "[#{alg}] sign!", %{
+      request = Net::HTTP::Post.new(uri)
+      request["content-type"] = "application/json"
+      request.body = '{"hello":"world"}'
+      Linzer.sign!(request, key: key, components: components)
+    }
+  end
+end

data/benchmarks/verify.rb

@@ -0,0 +1,68 @@
+require "benchmark_driver"
+require "openssl"
+
+BENCH_ALGS = %i[
+  ed25519
+  ecdsa_p256_sha256
+  ecdsa_p384_sha384
+  rsa_v1_5_sha256
+  rsa_pss_sha512
+  hmac_sha256
+  jws_ed25519
+]
+
+puts "Linzer.verify! benchmark — supported algorithms"
+puts `git show HEAD | head -1 | cut -b 1-15`
+puts "Ruby #{RUBY_VERSION} / #{RUBY_PLATFORM}"
+puts "OpenSSL #{OpenSSL::VERSION}"
+puts Time.now.utc
+
+BENCH_ALGS.each do |alg|
+  next if alg == :rsa_pss_sha512 && RUBY_VERSION < "3.1.0"
+  Benchmark.driver do |x|
+    x.prelude <<~RUBY
+      require "bundler/setup"
+      require "linzer"
+      require "linzer/jws"
+
+      def generate_linzer_key(alg)
+        case alg
+        when :ed25519, :ecdsa_p256_sha256, :ecdsa_p384_sha384, :hmac_sha256
+          Linzer.public_send(:"generate_#{alg}_key", "bench-#{alg}")
+        when :rsa_v1_5_sha256, :rsa_pss_sha512
+          Linzer.public_send(:"generate_#{alg}_key", 2048, "bench-#{alg}")
+        when :jws_ed25519
+          Linzer.generate_jws_key(algorithm: "EdDSA")
+        else
+          raise ArgumentError, "Unknown algorithm!"
+        end
+      end
+
+      key = generate_linzer_key(:"#{alg}")
+      uri        = URI("https://example.com/api/resource")
+      components = %w[@method @path @authority content-type]
+
+      request = Net::HTTP::Post.new(uri)
+      request["content-type"] = "application/json"
+      request.body = '{"hello":"world"}'
+
+      Linzer.sign!(request, key: key, components: components)
+
+      # Capture the signed headers so we can rebuild identical requests
+      sig_header   = request["signature"]
+      input_header = request["signature-input"]
+    RUBY
+
+    puts "\n#{alg}:\n#{"#" * 70}\n\n"
+
+    x.report "[#{alg}] verify!", %{
+      req = Net::HTTP::Post.new(uri)
+      req["content-type"]    = "application/json"
+      req.body               = '{"hello":"world"}'
+      req["signature"]       = sig_header
+      req["signature-input"] = input_header
+
+      Linzer.verify!(req, key: key)
+    }
+  end
+end

data/lib/linzer/common.rb

@@ -26,15 +26,25 @@ module Linzer
     #   # "@path": /foo
     #   # "content-type": application/json
     #   # "@signature-params": ("@method" "@path" "content-type");created=1618884473
-    def signature_base(message, serialized_components, parameters)
-      signature_base =
-        serialized_components.each_with_object(+"") do |component, base|
-          base << "%s\n" % signature_base_line(component, message)
+    def signature_base(message, serialized_components, parameters, field_ids: nil)
+      buf = +""
+
+      if field_ids
+        i = 0
+        len = serialized_components.size
+        while i < len
+          buf << serialized_components[i] << ": " << String(message[field_ids[i]]) << "\n"
+          i += 1
+        end
+      else
+        serialized_components.each do |component|
+          buf << signature_base_line(component, message) << "\n"
         end
+      end
 
-      signature_base << signature_params_line(serialized_components, parameters)
+      buf << signature_params_line(serialized_components, parameters)
 
-      signature_base
+      buf
     end
     module_function :signature_base
 
@@ -57,13 +67,14 @@ module Linzer
     # @param serialized_components [Array<String>] The covered components
     # @param parameters [Hash] Signature parameters
     # @return [String] The formatted @signature-params line
-    def signature_params_line(serialized_components, parameters)
-      identifiers = serialized_components.map { |c| Starry.parse_item(c) }
+    SERIALIZED_SIGNATURE_PARAMS = Starry.serialize("@signature-params").freeze
+    private_constant :SERIALIZED_SIGNATURE_PARAMS
 
-      signature_params =
-        Starry.serialize([Starry::InnerList.new(identifiers, parameters)])
+    def signature_params_line(serialized_components, parameters)
+      params_str = HTTP::StructuredField.serialize_parameters(parameters)
+      components_str = serialized_components.join(" ")
 
-      "%s: %s" % [Starry.serialize("@signature-params"), signature_params]
+      "#{SERIALIZED_SIGNATURE_PARAMS}: (#{components_str})#{params_str}"
     end
     module_function :signature_params_line
 
@@ -76,18 +87,30 @@ module Linzer
     # @raise [Error] If @signature-params is in the components
     # @raise [Error] If any component is missing from the message
     # @raise [Error] If any component is duplicated
-    def validate_components(message, components)
-      if components.include?('"@signature-params"') ||
-          components.any? { |c| c.start_with?('"@signature-params"') }
-        raise Error.new "Invalid component in signature input"
-      end
+    def validate_components(message, components, field_ids: nil)
+      has_params = false
+      missing = "Cannot verify signature. Missing component in message"
+      invalid = "Invalid component in signature input"
 
-      msg = "Cannot verify signature. Missing component in message: %s"
-      components.each do |c|
-        raise Error.new msg % "\"#{c}\"" unless message.field?(c)
+      if field_ids
+        i = 0
+        len = components.size
+        while i < len
+          c = components[i]
+          raise Error, invalid if c.include?("@signature-params")
+          has_params = true if !has_params && c.include?(";")
+          raise Error, "#{missing}: \"#{c}\"" unless message.field?(field_ids[i])
+          i += 1
+        end
+      else
+        components.each do |c|
+          raise Error, invalid if c.include?("@signature-params")
+          has_params = true if !has_params && c.include?(";")
+          raise Error, "#{missing}: \"#{c}\"" unless message.field?(c)
+        end
       end
 
-      validate_uniqueness components
+      validate_uniqueness(components) if has_params || components.size != components.uniq.size
     end
 
     # Validates that there are no duplicate components.
@@ -98,7 +121,14 @@ module Linzer
     # @param components [Array<String>] Component identifiers to check
     # @raise [Error] If any component appears more than once
     def validate_uniqueness(components)
-      msg = "Invalid signature. Duplicated component in signature input."
+      duplicated = "Invalid signature. Duplicated component in signature input."
+
+      # String-level duplicates are always invalid
+      raise Error, duplicated if components.size != components.uniq.size
+
+      # If any component has parameters, also check for semantic duplicates
+      # (e.g. ;bs;req vs ;req;bs are semantically equal but different strings)
+      return unless components.any? { |c| c.include?(";") }
 
       uniq_components =
         components
@@ -110,7 +140,7 @@ module Linzer
               .uniq { |comp| [comp.value, comp.parameters] }
           end
 
-      raise Error.new msg if components.count != uniq_components.count
+      raise Error, duplicated if components.count != uniq_components.count
     end
   end
 end

data/lib/linzer/ed25519.rb

@@ -46,13 +46,15 @@ module Linzer
         material.verify(nil, signature, data)
       end
 
+      private
+
       # @return [Boolean] true if this key contains public key material
-      def public?
+      def compute_public?
         has_pem_public?
       end
 
       # @return [Boolean] true if this key contains private key material
-      def private?
+      def compute_private?
         has_pem_private?
       end
     end

data/lib/linzer/hmac.rb

@@ -54,18 +54,6 @@ module Linzer
         OpenSSL.secure_compare(signature, sign(data))
       end
 
-      # HMAC keys can always sign (they contain the secret).
-      # @return [Boolean] true if key material is present
-      def private?
-        !material.nil?
-      end
-
-      # HMAC keys are symmetric, not public/private.
-      # @return [Boolean] always false for HMAC keys
-      def public?
-        false
-      end
-
       # Returns a safe string representation that doesn't leak the secret.
       #
       # The key material is intentionally excluded from the output to prevent
@@ -82,6 +70,20 @@ module Linzer
         oid = Digest::SHA2.hexdigest(object_id.to_s)[48..63]
         "#<%s:0x%s %s>" % [self.class, oid, vars.join(", ")]
       end
+
+      private
+
+      # HMAC keys can always sign (they contain the secret).
+      # @return [Boolean] true if key material is present
+      def compute_private?
+        !material.nil?
+      end
+
+      # HMAC keys are symmetric, not public/private.
+      # @return [Boolean] always false for HMAC keys
+      def compute_public?
+        false
+      end
     end
   end
 end

data/lib/linzer/http/structured_field.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Linzer
+  module HTTP
+    # Utilities for serializing HTTP Structured Fields as defined in RFC 8941.
+    #
+    # This module currently provides helpers for serializing HTTP Message
+    # Signature parameters as used by RFC 9421.
+    #
+    # @see https://www.rfc-editor.org/rfc/rfc8941 RFC 8941
+    # @see https://www.rfc-editor.org/rfc/rfc9421 RFC 9421
+    module StructuredField
+      # Serializes signature parameters to the RFC 8941 string format.
+      #
+      # Integers are bare, strings are double-quoted. This covers all
+      # parameter types used in RFC 9421 signatures (created, expires,
+      # keyid, nonce, alg, tag).
+      #
+      # @example Serialize signature parameters
+      #   StructuredField.serialize_parameters(
+      #     created: 1700000000,
+      #     keyid: "my-key"
+      #   )
+      #   # => ';created=1700000000;keyid="my-key"'
+      #
+      # @param parameters [Hash{Symbol,String => Object}]
+      #   The parameters to serialize.
+      #
+      # @return [String]
+      #   The serialized structured field parameter string.
+      #
+      def self.serialize_parameters(parameters)
+        params_str = +""
+        parameters.each do |key, value|
+          params_str << case value
+          when Integer
+            ";#{key}=#{value}"
+          when String
+            ";#{key}=\"#{value}\""
+          else
+            ";#{key}=#{value}"
+          end
+        end
+        params_str
+      end
+    end
+  end
+end

data/lib/linzer/jws.rb

@@ -101,18 +101,18 @@ module Linzer
         algo.verify(data: data, signature: signature, verification_key: verify_key)
       end
 
+      private
+
       # @return [Boolean] true if this key can verify signatures
-      def public?
+      def compute_public?
         !!verify_key
       end
 
       # @return [Boolean] true if this key can create signatures
-      def private?
+      def compute_private?
         !!signing_key
       end
 
-      private
-
       # Resolves the appropriate JWT algorithm implementation.
       # @return [JWT::JWA::SigningAlgorithm] The algorithm implementation
       # @raise [Error] If the algorithm cannot be determined