linzer 0.7.9 → 0.8.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91f1e3986fae03eb9bf01d4dc8e9c919cd7072ea3ae0f8168099261da0da8c11
-  data.tar.gz: fb07600d19e8e2198e7cbcfb910516d9300e3aa89d94e81e3bc3ebd6a9d007e8
+  metadata.gz: 7a917fda2b4d4646e642ba3a52d11bd41a500b5bfed044142a6e0434e0ef1c94
+  data.tar.gz: 8d9296ba21595cba696532a41b20f123569d3b31de0730ba6e7e6f693e87e009
 SHA512:
-  metadata.gz: aed32987b8ea9fc398ef1d263a94ce3df3ec86e8cd331d2e9b23383c0c6de1db3f0bdaa621990eb1809c210b0ae3f38b045abd2e8e48229a9ec8129cf4213c65
-  data.tar.gz: 26a21c99d8e383af31395f5ebfa5581b0fedf126bb1bb806db3cb1eb0f0d89306dde3af7bf54100cd0251235f54e5cd4f852f8d61007b74fe079716b4447986a
+  metadata.gz: 2f6b61e4a340594891976d77b651527b8e0d49ff9ab11d73c56f01b5baecc1ad3fdf8ad23d987652496929ef30495cb116ba04a53f1b7ef2d881e8c1c1cfa1c9
+  data.tar.gz: fb4800f527d14823e9ed76b776056fe20a60f35fc3e08c30ce15c05758648476f8489c2d8bb89851fe2c77eeff56891b96ec955663bf08b7b6326cdf4425c881

data/.standard.yml

@@ -9,3 +9,4 @@ ignore:
     - Layout/ArgumentAlignment
     - Style/EmptyCaseCondition
     - Style/RescueModifier
+    - Layout/MultilineMethodCallBraceLayout

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [Unreleased]
 
+## [0.8.0.beta2] - 2026-05-20
+
+- Add Web Bot Auth support, implementing the current IETF draft
+  (draft-meunier-web-bot-auth-architecture-05).
+  Includes recommended signature parameter defaults, nonce generation,
+  and optional Signature-Agent header handling.
+
+## [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
@@ -482,6 +490,61 @@ anything that to responds to `#to_i`, including an `ActiveSupport::Duration`.
 If the signature is older than the allowed window, verification
 fails with an error.
 
+## Web Bot Auth
+
+Linzer supports the Web Bot Auth authentication mechanism, which allows
+automated clients to identify themselves using HTTP Message Signatures
+(as defined in RFC 9421).
+
+This is useful for distinguishing legitimate automated traffic from
+anonymous or potentially abusive requests.
+
+For more details on Web Bot Auth, refer to the
+[relevant IETF drafts](https://datatracker.ietf.org/wg/webbotauth/documents/)
+or to additional resources such as
+[this Cloudflare article](https://blog.cloudflare.com/web-bot-auth/).
+
+When enabled, as shown in the examples below, Linzer adds the required
+signature headers to identify the client as an automated agent:
+
+- Plain Linzer:
+
+```ruby
+
+Linzer.sign!(
+  request,
+  key:     key,
+  label:   "sig1",
+  profile: :web_bot_auth
+  # or override/set specific parameters like the following:
+  # profile: Linzer::Signing::Profile.web_bot_auth(agent: "https://...")
+)
+```
+
+- http.rb gem:
+
+```ruby
+require "linzer/http/signature_feature"
+
+response = HTTP.headers(date: Time.now.utc.httpdate, foo: "bar")
+               .use(http_signature: {key: key, profile: :web_bot_auth}
+               .get(url)
+```
+
+- Faraday:
+
+```ruby
+require "linzer/faraday"
+
+conn = Faraday.new(url: api_url) do |builder|
+  builder.request :http_signature, key: signing_key,
+                                   components: components,
+                                   profile: :web_bot_auth,
+                                   params: signature_params
+end
+response = conn.post("/task")
+```
+
 ## Supported algorithms
 
 Linzer currently supports the following signature algorithms:

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/faraday/http_signature/middleware.rb

@@ -107,7 +107,16 @@ module Faraday
       #   @return [Boolean] when +true+ (default), raises
       #     {VerifyError} on verification failure; when +false+,
       #     sets +env[:http_signature_verified]+ to +false+ and continues
-      class Options < Faraday::Options.new(:key, :sign_request, :sign_key, :components, :verify_response, :verify_key, :params, :strict)
+      # @!attribute [rw] profile
+      #   Optional HTTP Message Signatures signing profile.
+      #
+      #   When set, the profile is passed to {Linzer.sign!} and may provide
+      #   default covered components and signature parameters.
+      #
+      #   @return [Symbol, Linzer::Signature::Profile::Base, nil]
+      #     a registered profile name, a profile instance, or +nil+ to use
+      #     the default signing behavior
+      class Options < Faraday::Options.new(:key, :sign_request, :sign_key, :components, :verify_response, :verify_key, :params, :strict, :profile)
         # Returns the generic key.
         # @return [Linzer::Key, nil]
         def key
@@ -146,6 +155,13 @@ module Faraday
         def params
           Hash(self[:params])
         end
+
+        # Returns the signing profile configuration.
+        #
+        # @return [Symbol, Linzer::Signature::Profile::Base, nil]
+        def profile
+          self[:profile]
+        end
       end
 
       # Creates a new middleware instance.
@@ -186,10 +202,15 @@ module Faraday
 
         key = resolve_signing_key
         request = Linzer::Faraday::Utils.create_request(env)
-        message = Linzer::Message.new(request)
 
-        signature = Linzer.sign(key, message, options.components, options.params)
-        env.request_headers.merge!(signature.to_h)
+        Linzer.sign! request,
+                     key:        key,
+                     components: options.components,
+                     params:     options.params,
+                     profile:    options.profile
+
+        signature_headers = request.headers.slice("signature", "signature-input")
+        env.request_headers.merge!(signature_headers)
         env
       rescue Linzer::Error => e
         raise SigningError, e if options.strict?

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 = HTTP::StructuredField.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
@@ -106,11 +136,11 @@ module Linzer
           .flat_map
           .with_index do |group, idx|
             group
-              .map  { |comp| Starry.parse_item(idx.zero? ? comp[1..] : comp) }
+              .map  { |comp| HTTP::StructuredField.parse_item(idx.zero? ? comp[1..] : comp) }
               .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