linzer 0.7.0.beta2 → 0.7.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd7b5e233ec42d94c7040f774097c612850eef9c5795a2c8d3251bc618c8df5f
-  data.tar.gz: 53cc818e2fc68fe1f6b3c89414a5b0d2393e1b8cfa8e4c9f3ba9076ce537f81c
+  metadata.gz: 65ccb6f89aab47730e202a8ad376b2ceb310213b2a140d194b2b6fd285aa710f
+  data.tar.gz: 485efd259e353048041528c38f0072945592cfe6f8d4c4e6ea20af5546e6cb94
 SHA512:
-  metadata.gz: 93e5fb0d4fd0cd534691102a02efa8ae14589d12ee3636f86d10d19e57104b1bb122f950c9191c5fb40264fc453a31d33aa1369fac0fe34451e74108ce9c6a5c
-  data.tar.gz: e5b12b53e46f7958c560cb579111c14eab85da6a047effcdb599d39f955fe38b89175faef1937a963890c8d8254763c54314ea95c4eff70815fc0c0b8c396551
+  metadata.gz: a01a27867e6dd628365268f1106880b7f61ad80b4d314ea336e21e4f1a4edbb17394d0c7da4f23256566e34a6acb2e6eec54680461141d917189a37219d3c84e
+  data.tar.gz: 2efef6b1fcad53964e1f54c8f1453b2ad3aa481ca98960ada2e735439d0736624118a99ab58d1f73fdef517f9802e1453215e17bfc660e56dae81cd5b044769d

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.7.0.beta3] - 2025-05-06 (aka the ["MiniDebConf Hamburg 2025"](https://wiki.debian.org/DebianEvents/de/2025/MiniDebConfHamburg) release)
+
+- Refactor to improve Linzer APIs and streamline its usage along with different
+  HTTP libraries.
+
 ## [0.7.0.beta2] - 2025-04-13
 
 - Refactor and improve Rack::Auth::Signature code organization.

data/README.md

@@ -23,7 +23,7 @@ Or just `gem install linzer`.
 
 ### TL;DR: I just want to protect my application!!
 
-Add the following middleware to you run Rack application and configure it
+Add the following middleware to your Rack application and configure it
 as needed, e.g.:
 
 ```ruby
@@ -58,46 +58,40 @@ look at
 
 To learn about more specific scenarios or use cases, keep reading on below.
 
-### To sign a HTTP message:
+### To sign a HTTP request:
 
 ```ruby
 key = Linzer.generate_ed25519_key
 # => #<Linzer::Ed25519::Key:0x00000fe13e9bd208
 
-headers = {
-  "date" => "Fri, 23 Feb 2024 17:57:23 GMT",
-  "x-custom-header" => "foo"
-}
-
-request = Linzer.new_request(:post, "/some_uri", {}, headers)
-# => #<Rack::Request:0x0000000104c1c8c0
-#       @env={"HTTP_DATE"=>"Fri, 23 Feb 2024 17:57:23 GMT", "HTTP_X_CUSTOM..."
-#       @params=nil>
-
-message = Linzer::Message.new(request)
-# => #<Linzer::Message:0x0000000104afa960
-#       @operation=#<Rack::Request:0x00000001049754a0
-#       @env={"HTTP_DATE"=>"Fri, 23 Feb 2024 17:57:23 GMT", "HTTP_X_CUSTOM..."
-#       @params=nil>>
-
-fields = %w[date x-custom-header @method @path]
-
-signature = Linzer.sign(key, message, fields)
-# => #<Linzer::Signature:0x0000000111f77ad0 ...
-
-pp signature.to_h
-# => {"signature"=>"sig1=:Cv1TUCxUpX+5SVa7pH0Xh...",
-#  "signature-input"=>"sig1=(\"date\" \"x-custom-header\" ..."}
+uri = URI("https://example.org/api/task")
+request = Net::HTTP::Get.new(uri)
+request["date"] = Time.now.to_s
+
+Linzer.sign!(
+  request,
+  key: key,
+  components: %w[@method @request-target date],
+  label: "sig1",
+  params: {
+    created: Time.now.to_i
+  }
+)
+
+request["signature"]
+# => "sig1=:Cv1TUCxUpX+5SVa7pH0Xh..."
+request["signature-input"]
+# => "sig1=(\"@method\" \"@request-target\" \"date\" ..."}
 ```
 
-### Use the message signature with any HTTP client:
+### Use the signed request with an HTTP client:
 
 ```ruby
 require "net/http"
 
-http = Net::HTTP.new("localhost", 9292)
+http = Net::HTTP.new(uri.host, uri.port)
 http.set_debug_output($stderr)
-response = http.post("/some_uri", "data", headers.merge(signature.to_h))
+response = http.request(request)
 # opening connection to localhost:9292...
 # opened
 # <- "POST /some_uri HTTP/1.1\r\n
@@ -131,7 +125,123 @@ response = http.post("/some_uri", "data", headers.merge(signature.to_h))
 # => #<Net::HTTPOK 200 OK readbody=true>
 ```
 
-### To verify a valid signature:
+### To verify an incoming request on the server side:
+
+The middleware `Rack::Auth::Signature` can be used for this scenario
+[as shown above](#tldr-i-just-want-to-protect-my-application).
+
+Or directly in the application controller (or routes), the incoming request can
+be verified with the following approach:
+
+```ruby
+post "/foo" do
+  request
+  # =>
+  # #<Sinatra::Request:0x000000011e5a5d60
+  #  @env=
+  #   {"GATEWAY_INTERFACE" => "CGI/1.1",
+  #   "PATH_INFO" => "/api",
+  # ...
+
+  result = Linzer.verify!(request, key: some_client_key)
+  # => true
+  ...
+end
+```
+
+If the signature is missing or invalid, the verification method will raise an
+exception with a message clarifying why the request signature failed verification.
+
+Also, for additional flexibility on the server side, the method above can take
+a block with the `keyid` parameter extracted from the signature (if any) as argument.
+This can be useful to retrieve key data from databases/caches on the server side, e.g.:
+
+```ruby
+get "/bar" do
+  ...
+  result = Linzer.verify!(request) do |keyid|
+    retrieve_pubkey_from_db(db_client, keyid)
+  end
+  # => true
+  ...
+end
+```
+
+### To verify a received response on the client side:
+
+It's similar to verifying requests, the same method is used, see example below:
+
+```ruby
+response
+# => #<Net::HTTPOK 200 OK readbody=true>
+response.body
+# => "protected"
+pubkey = Linzer.new_ed25519_key(IO.read("pubkey.pem"))
+result = Linzer.verify!(response, key: pubkey, no_older_than: 600)
+# => true
+```
+
+### To sign an outgoing response on the server side:
+
+Again, the same principle used to sign outgoing requests, the same method is used,
+see example below:
+
+```ruby
+put "/baz" do
+  ...
+  response
+  # => #<Sinatra::Response:0x0000000109ac40b8 ...
+  response.headers["x-custom-app-header"] = "..."
+  Linzer.sign!(response,
+    key: my_key,
+    components: %w[@status content-type content-digest x-custom-app-header],
+    label: "sig1",
+    params: {
+      created: Time.now.to_i
+    }
+  )
+  response["signature"]
+  # => "sig1=:2TPCzD4l48bg6LMcVXdV9u..."
+  response["signature-input"]
+  # => "sig1=(\"@status\" \"content-type\" \"content-digest\"..."
+  ...
+end
+```
+
+### What do you do if you want to sign/verify requests and responses with your preferred HTTP ruby library/framework (not using Rack or `Net::HTTP`, for example)?
+
+You can provide an adapter class and then register it with this library.
+For guidance on how to implement such adapters, you can consult an
+[example adapter for http gem response](https://github.com/nomadium/linzer/blob/master/lib/linzer/message/adapter/http_gem/response.rb)
+included with this gem or the ones
+[provided out of the box](https://github.com/nomadium/linzer/blob/master/lib/linzer/message/adapter).
+
+For how to register a custom adapter and how to verify signatures in a response,
+see this example:
+
+```ruby
+Linzer::Message.register_adapter(HTTP::Response, MyOwnResponseAdapter)
+response = HTTP.get("http://www.example.com/api/service/task")
+# => #<HTTP::Response/1.1 200 OK ...
+response["signature"]
+=> "sig1=:oqzDlQmfejfT..."
+response["signature-input"]
+=> "sig1=(\"@status\" \"foo\");created=1746480237"
+result = Linzer.verify!(response, key: my_key)
+# => true
+```
+---
+
+Furthermore, on some low-level scenarios where a user wants or needs additional
+control on how the signing and verification routines are performed, Linzer allows
+to manipulate instances of internal HTTP messages (requests & responses, see
+`Linzer::Message` class and available adapters), signature objects
+(`Linzer::Signature`) and how to register additional message adapters for any
+HTTP ruby library not supported out of the box by this gem.
+
+See below for a few examples of these scenarios.
+
+#### To verify a valid signature:
 
 ```ruby
 test_ed25519_key_pub = key.material.public_to_pem
@@ -140,12 +250,6 @@ test_ed25519_key_pub = key.material.public_to_pem
 pubkey = Linzer.new_ed25519_public_key(test_ed25519_key_pub, "some-key-ed25519")
 # => #<Linzer::Ed25519::Key:0x00000fe19b9384b0
 
-# if you have to, there is a helper method to build a request object on the server side
-# although any standard Ruby web server or framework (Sinatra, Rails, etc) should expose
-# a request object and this should not be required for most cases.
-#
-# request = Linzer.new_request(:post, "/some_uri", {}, headers)
-
 message = Linzer::Message.new(request)
 
 signature = Linzer::Signature.build(message.headers)
@@ -163,14 +267,14 @@ Linzer.verify(pubkey, message, signature, no_older_than: 500)
 `no_older_than` expects a number of seconds, but you can pass anything that to responds to `#to_i`, including an `ActiveSupport::Duration`.
 `::verify` will raise if the `created` parameter of the signature is older than the given number of seconds.
 
-### What if an invalid signature if verified?
+#### What if an invalid signature if verified?
 
 ```ruby
 result = Linzer.verify(pubkey, message, signature)
 lib/linzer/verifier.rb:38:in `verify_or_fail': Failed to verify message: Invalid signature. (Linzer::Error)
 ```
 
-### HTTP responses are also supported
+#### HTTP responses are also supported
 
 HTTP responses can also be signed and verified in the same way as requests.
 

data/lib/linzer/message/adapter/abstract.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      class Abstract
+        def initialize(operation, **options)
+          raise Linzer::Error, "Cannot instantiate an abstract class!"
+        end
+
+        def request?
+          self.class.to_s.include?("Request")
+        end
+
+        def response?
+          self.class.to_s.include?("Response")
+        end
+
+        # XXX: attached request as specified in RFC has to be tested for Net::HTTP classes
+        # and custom HTTP message classes
+        def attached_request?
+          response? && !!@attached_request
+        end
+
+        def field?(f)
+          !!self[f]
+        end
+
+        def [](field_name)
+          name = parse_field_name(field_name)
+          return nil if name.nil?
+
+          if field_name.start_with?("@")
+            retrieve(name, :derived)
+          else
+            retrieve(name, :field)
+          end
+        end
+
+        def headers
+          raise Linzer::Error, "Sub-classes are required to implement this method!"
+        end
+
+        def attach!(signature)
+          raise Linzer::Error, "Sub-classes are required to implement this method!"
+        end
+
+        private
+
+        def parse_field_name(field_name)
+          if field_name&.start_with?("@")
+            Starry.parse_item(field_name[1..])
+          else
+            Starry.parse_item(field_name)
+          end
+        rescue => _
+          nil
+        end
+
+        def validate_attached_request(message)
+          msg = "The attached message is not a valid HTTP request!"
+          raise Linzer::Error, msg unless message.request?
+        end
+
+        def validate_parameters(name, method)
+          has_unknown = name.parameters.any? { |p, _| !KNOWN_PARAMETERS.include?(p) }
+          return nil if has_unknown
+
+          has_name = name.parameters["name"]
+          has_req  = name.parameters["req"]
+          has_sf   = name.parameters["sf"] || name.parameters.key?("key")
+          has_bs   = name.parameters["bs"]
+          value    = name.value
+
+          # Section 2.2.8 of RFC 9421
+          return nil if has_name && value != :"query-param"
+
+          # No derived values come from trailers section
+          return nil if method == :derived && name.parameters["tr"]
+
+          # From: 2.1. HTTP Fields:
+          # The bs parameter, which requires the raw bytes of the field values
+          # from the message, is not compatible with the use of the sf or key
+          # parameters, which require the parsed data structures of the field
+          # values after combination
+          return nil if has_sf && has_bs
+
+          # req param only makes sense on responses with an associated request
+          # return nil if has_req && (!response? || !attached_request?)
+          return nil if has_req && !response?
+
+          name
+        end
+
+        KNOWN_PARAMETERS = %w[sf key bs req tr name]
+        private_constant :KNOWN_PARAMETERS
+
+        def retrieve(name, method)
+          if !name.parameters.empty?
+            valid_params = validate_parameters(name, method)
+            return nil if !valid_params
+          end
+
+          has_req = name.parameters["req"]
+          has_sf  = name.parameters["sf"] || name.parameters.key?("key")
+          has_bs  = name.parameters["bs"]
+
+          if has_req
+            name.parameters.delete("req")
+            return req(name, method)
+          end
+
+          value = send(method, name)
+
+          case
+          when has_sf
+            key = name.parameters["key"]
+            sf(value, key)
+          when has_bs then bs(value)
+          else value
+          end
+        end
+
+        def sf(value, key = nil)
+          dict = Starry.parse_dictionary(value)
+
+          if key
+            obj = dict[key]
+            Starry.serialize(obj.is_a?(Starry::InnerList) ? [obj] : obj)
+          else
+            Starry.serialize(dict)
+          end
+        end
+
+        def bs(value)
+          Starry.serialize(value.encode(Encoding::ASCII_8BIT))
+        end
+
+        def tr(trailer)
+          @operation.body.trailers[trailer.value.to_s]
+        end
+
+        def req(field, method)
+          case method
+          when :derived then @attached_request["@#{field}"]
+          when :field   then @attached_request[field.to_s]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter/http_gem/response.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+# Example HTTP message adapter for HTTP::Response class from http ruby gem.
+# https://github.com/httprb/http
+# It's not required automatically to avoid making http gem a dependency.
+#
+module Linzer
+  class Message
+    module Adapter
+      module HTTPGem
+        class Response < Abstract
+          def initialize(operation, **options)
+            @operation = operation
+            freeze
+          end
+
+          def headers
+            @operation.headers
+          end
+
+          # XXX: this implementation is incomplete, e.g.: ;tr parameter is not supported yet
+          def [](field_name)
+            return @operation.code if field_name == "@status"
+            @operation[field_name]
+          end
+
+          def attach!(signature)
+            signature.to_h.each { |h, v| @operation[h] = v }
+            @operation
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter/net_http/request.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Linzer
+  class Message
+    module Adapter
+      module NetHTTP
+        class Request < Abstract
+          def initialize(operation, **options)
+            @operation = operation
+            freeze
+          end
+
+          def headers
+            @operation.each_header.to_h
+          end
+
+          def attach!(signature)
+            signature.to_h.each { |h, v| @operation[h] = v }
+            @operation
+          end
+
+          private
+
+          def derived(name)
+            case name.value
+            when :method           then @operation.method
+            when :"target-uri"     then @operation.uri.to_s
+            when :authority        then @operation.uri.authority.downcase
+            when :scheme           then @operation.uri.scheme.downcase
+            when :"request-target" then @operation.uri.request_uri
+            when :path             then @operation.uri.path
+            when :query            then "?%s" % String(@operation.uri.query)
+            when :"query-param"    then query_param(name)
+            end
+          end
+
+          def query_param(name)
+            param_name = name.parameters["name"]
+            return nil if !param_name
+            decoded_param_name = URI.decode_uri_component(param_name)
+            params = CGI.parse(@operation.uri.query)
+            URI.encode_uri_component(params[decoded_param_name]&.first)
+          end
+
+          def field(name)
+            has_tr = name.parameters["tr"]
+            return nil if has_tr # HTTP requests don't have trailer fields
+            value = @operation[name.value.to_s]
+            value.dup&.strip
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter/net_http/response.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      module NetHTTP
+        class Response < Abstract
+          def initialize(operation, **options)
+            @operation = operation
+            attached_request = options[:attached_request]
+            @attached_request = attached_request ? Message.new(attached_request) : nil
+            validate_attached_request @attached_request if @attached_request
+            freeze
+          end
+
+          def headers
+            @operation.each_header.to_h
+          end
+
+          # XXX: this implementation is incomplete, e.g.: ;tr parameter is not supported yet
+          def [](field_name)
+            return @operation.code.to_i if field_name == "@status"
+            @operation[field_name]
+          end
+
+          def attach!(signature)
+            signature.to_h.each { |h, v| @operation[h] = v }
+            @operation
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter/rack/common.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      module Rack
+        module Common
+          DERIVED_COMPONENT = {
+            method:           :request_method,
+            authority:        :authority,
+            path:             :path_info,
+            status:           :status,
+            "target-uri":     :url,
+            scheme:           :scheme,
+            "request-target": :fullpath,
+            query:            :query_string
+          }.freeze
+          private_constant :DERIVED_COMPONENT
+
+          private
+
+          def validate
+            msg = "Message instance must be an HTTP request or response"
+            raise Error.new msg if response? == request?
+          end
+
+          def validate_header_name(name)
+            raise ArgumentError.new, "Blank header name." if name.empty?
+            name.to_str
+          rescue => ex
+            err_msg = "Invalid header name: '#{name}'"
+            raise Linzer::Error.new, err_msg, cause: ex
+          end
+
+          def rack_header_name(field_name)
+            validate_header_name field_name
+
+            rack_name = field_name.upcase.tr("-", "_")
+            case field_name.downcase
+            when "content-type", "content-length"
+              rack_name
+            else
+              "HTTP_#{rack_name}"
+            end
+          end
+
+          def rack_request_headers(rack_request)
+            rack_request
+              .each_header
+              .to_h
+              .select do |k, _|
+                k.start_with?("HTTP_") || %w[CONTENT_TYPE CONTENT_LENGTH].include?(k)
+              end
+              .transform_keys { |k| k.downcase.tr("_", "-") }
+              .transform_keys do |k|
+                %w[content-type content-length].include?(k) ? k : k.gsub(/^http-/, "")
+              end
+          end
+
+          def derived(name)
+            method = DERIVED_COMPONENT[name.value]
+
+            value = case name.value
+            when :query         then derive(@operation, method)
+            when :"query-param" then query_param(name)
+            end
+
+            return nil if !method && !value
+            value || derive(@operation, method)
+          end
+
+          def field(name)
+            has_tr = name.parameters["tr"]
+            if has_tr
+              value = tr(name)
+            else
+              if request?
+                rack_header_name = rack_header_name(name.value.to_s)
+                value = @operation.env[rack_header_name]
+              end
+              value = @operation.headers[name.value.to_s] if response?
+            end
+            value.dup&.strip
+          end
+
+          def derive(operation, method)
+            return nil unless operation.respond_to?(method)
+            value = operation.public_send(method)
+            return "?" + value    if method == :query_string
+            return value.downcase if %i[authority scheme].include?(method)
+            value
+          end
+
+          def query_param(name)
+            param_name = name.parameters["name"]
+            return nil if !param_name
+            decoded_param_name = URI.decode_uri_component(param_name)
+            URI.encode_uri_component(@operation.params.fetch(decoded_param_name))
+          rescue => _
+            nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter/rack/request.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      module Rack
+        class Request < Abstract
+          include Common
+
+          def initialize(operation, **options)
+            @operation = operation
+            validate
+            freeze
+          end
+
+          def headers
+            rack_request_headers(@operation)
+          end
+
+          def attach!(signature)
+            signature.to_h.each do |h, v|
+              @operation.set_header(rack_header_name(h), v)
+            end
+            @operation
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter/rack/response.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      module Rack
+        class Response < Abstract
+          include Common
+
+          def initialize(operation, **options)
+            @operation = operation
+            validate
+            attached_request = options[:attached_request]
+            @attached_request = attached_request ? Message.new(attached_request) : nil
+            validate_attached_request @attached_request if @attached_request
+            freeze
+          end
+
+          def headers
+            @operation.headers
+          end
+
+          def attach!(signature)
+            signature.to_h.each { |h, v| @operation[h] = v }
+            @operation
+          end
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message/adapter.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "adapter/abstract"
+require_relative "adapter/rack/common"
+require_relative "adapter/rack/request"
+require_relative "adapter/rack/response"
+require_relative "adapter/net_http/request"
+require_relative "adapter/net_http/response"

data/lib/linzer/message/wrapper.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Wrapper
+      @adapters = {
+        Rack::Request     => Linzer::Message::Adapter::Rack::Request,
+        Rack::Response    => Linzer::Message::Adapter::Rack::Response,
+        Net::HTTPRequest  => Linzer::Message::Adapter::NetHTTP::Request,
+        Net::HTTPResponse => Linzer::Message::Adapter::NetHTTP::Response
+      }
+
+      class << self
+        def wrap(operation, **options)
+          adapter_class = adapters[operation.class]
+
+          if !adapter_class
+            ancestor = find_ancestor(operation)
+            fail_with_unsupported(operation) unless ancestor
+          end
+
+          (adapter_class || ancestor).new(operation, **options)
+        end
+
+        def register_adapter(operation_class, adapter_class)
+          adapters[operation_class] = adapter_class
+        end
+
+        private
+
+        attr_reader :adapters
+
+        def find_ancestor(operation)
+          adapters
+            .select { |klz, adpt| operation.is_a? klz }
+            .values
+            .first
+        end
+
+        def fail_with_unsupported(operation)
+          err_msg = <<~EOM
+            Unknown/unsupported HTTP message class: '#{operation.class}'!
+
+            Linzer supports custom HTTP messages implementation by register them first
+            with `Linzer::Message.register_adapter` method.
+          EOM
+          raise Linzer::Error, err_msg
+        end
+      end
+    end
+  end
+end

data/lib/linzer/message.rb

@@ -1,207 +1,28 @@
 # frozen_string_literal: true
 
+require "forwardable"
+
 module Linzer
   class Message
+    extend Forwardable
+
     def initialize(operation, attached_request: nil)
-      @operation = operation
-      validate
-      @attached_request = attached_request ? Message.new(attached_request) : nil
+      @adapter = Wrapper.wrap(operation, attached_request: attached_request)
       freeze
     end
 
-    def request?
-      @operation.is_a?(Rack::Request) || @operation.respond_to?(:request_method)
-    end
-
-    def response?
-      @operation.is_a?(Rack::Response) || @operation.respond_to?(:status)
-    end
-
-    def attached_request?
-      !!@attached_request
-    end
-
-    def headers
-      return @operation.headers if response? || @operation.respond_to?(:headers)
+    # common predicates
+    def_delegators :@adapter, :request?, :response?, :attached_request?
 
-      Request.headers(@operation)
-    end
-
-    def field?(f)
-      !!self[f]
-    end
-
-    DERIVED_COMPONENT = {
-      method:           :request_method,
-      authority:        :authority,
-      path:             :path_info,
-      status:           :status,
-      "target-uri":     :url,
-      scheme:           :scheme,
-      "request-target": :fullpath,
-      query:            :query_string
-    }.freeze
+    # fields look up
+    def_delegators :@adapter, :headers, :field?, :[]
 
-    def [](field_name)
-      name = parse_field_name(field_name)
-      return nil if name.nil?
-
-      if field_name.start_with?("@")
-        retrieve(name, :derived)
-      else
-        retrieve(name, :field)
-      end
-    end
+    # to attach a signature to the underlying HTTP message
+    def_delegators :@adapter, :attach!
 
     class << self
-      def parse_structured_dictionary(str, field_name = nil)
-        Starry.parse_dictionary(str)
-      rescue Starry::ParseError => _
-        raise Error.new "Cannot parse \"#{field_name}\" field. Bailing out!"
-      end
-    end
-
-    private
-
-    def validate
-      msg = "Message instance must be an HTTP request or response"
-      raise Error.new msg if response? == request?
-    end
-
-    def parse_field_name(field_name)
-      if field_name&.start_with?("@")
-        Starry.parse_item(field_name[1..])
-      else
-        Starry.parse_item(field_name)
-      end
-    rescue => _
-      nil
-    end
-
-    def validate_parameters(name, method)
-      has_unknown = name.parameters.any? { |p, _| !KNOWN_PARAMETERS.include?(p) }
-      return nil if has_unknown
-
-      has_name = name.parameters["name"]
-      has_req  = name.parameters["req"]
-      has_sf   = name.parameters["sf"] || name.parameters.key?("key")
-      has_bs   = name.parameters["bs"]
-      value    = name.value
-
-      # Section 2.2.8 of RFC 9421
-      return nil if has_name && value != :"query-param"
-
-      # No derived values come from trailers section
-      return nil if method == :derived && name.parameters["tr"]
-
-      # From: 2.1. HTTP Fields:
-      # The bs parameter, which requires the raw bytes of the field values
-      # from the message, is not compatible with the use of the sf or key
-      # parameters, which require the parsed data structures of the field
-      # values after combination
-      return nil if has_sf && has_bs
-
-      # req param only makes sense on responses with an associated request
-      return nil if has_req && (!response? || !attached_request?)
-
-      name
-    end
-
-    KNOWN_PARAMETERS = %w[sf key bs req tr name]
-    private_constant :KNOWN_PARAMETERS
-
-    def retrieve(name, method)
-      if !name.parameters.empty?
-        valid_params = validate_parameters(name, method)
-        return nil if !valid_params
-      end
-
-      has_req = name.parameters["req"]
-      has_sf  = name.parameters["sf"] || name.parameters.key?("key")
-      has_bs  = name.parameters["bs"]
-
-      if has_req
-        name.parameters.delete("req")
-        return req(name, method)
-      end
-
-      value = send(method, name)
-
-      case
-      when has_sf
-        key = name.parameters["key"]
-        sf(value, key)
-      when has_bs then bs(value)
-      else value
-      end
-    end
-
-    def derived(name)
-      method = DERIVED_COMPONENT[name.value]
-
-      value = case name.value
-      when :query         then derive(@operation, method)
-      when :"query-param" then query_param(name)
-      end
-
-      return nil if !method && !value
-      value || derive(@operation, method)
-    end
-
-    def field(name)
-      has_tr = name.parameters["tr"]
-      if has_tr
-        value = tr(name)
-      else
-        if request?
-          rack_header_name = Request.rack_header_name(name.value.to_s)
-          value = @operation.env[rack_header_name]
-        end
-        value = @operation.headers[name.value.to_s] if response?
-      end
-      value.dup&.strip
-    end
-
-    def derive(operation, method)
-      return nil unless operation.respond_to?(method)
-      value = operation.public_send(method)
-      return "?" + value    if method == :query_string
-      return value.downcase if %i[authority scheme].include?(method)
-      value
-    end
-
-    def query_param(name)
-      param_name = name.parameters["name"]
-      return nil if !param_name
-      decoded_param_name = URI.decode_uri_component(param_name)
-      URI.encode_uri_component(@operation.params.fetch(decoded_param_name))
-    rescue => _
-      nil
-    end
-
-    def sf(value, key = nil)
-      dict = Starry.parse_dictionary(value)
-
-      if key
-        obj = dict[key]
-        Starry.serialize(obj.is_a?(Starry::InnerList) ? [obj] : obj)
-      else
-        Starry.serialize(dict)
-      end
-    end
-
-    def bs(value)
-      Starry.serialize(value.encode(Encoding::ASCII_8BIT))
-    end
-
-    def tr(trailer)
-      @operation.body.trailers[trailer.value.to_s]
-    end
-
-    def req(field, method)
-      case method
-      when :derived then @attached_request["@#{field}"]
-      when :field   then @attached_request[field.to_s]
+      def register_adapter(operation_class, adapter_class)
+        Wrapper.register_adapter(operation_class, adapter_class)
       end
     end
   end

data/lib/linzer/signature.rb

@@ -86,11 +86,17 @@ module Linzer
         raise Error.new "Unexpected value for covered components."
       end
 
+      def parse_structured_dictionary(str, field_name = nil)
+        Starry.parse_dictionary(str)
+      rescue Starry::ParseError => _
+        raise Error.new "Cannot parse \"#{field_name}\" field. Bailing out!"
+      end
+
       def parse_structured_field(hsh, field_name)
         # Serialized Structured Field values for HTTP are ASCII strings.
         # See: RFC 8941 (https://datatracker.ietf.org/doc/html/rfc8941)
         value = hsh[field_name].encode(Encoding::US_ASCII)
-        Message.parse_structured_dictionary(value, field_name)
+        parse_structured_dictionary(value, field_name)
       end
     end
   end

data/lib/linzer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Linzer
-  VERSION = "0.7.0.beta2"
+  VERSION = "0.7.0.beta3"
 end

data/lib/linzer.rb

@@ -5,12 +5,13 @@ require "openssl"
 require "rack"
 require "uri"
 require "stringio"
+require "net/http"
 
 require_relative "linzer/version"
 require_relative "linzer/common"
-require_relative "linzer/request"
-require_relative "linzer/response"
 require_relative "linzer/message"
+require_relative "linzer/message/adapter"
+require_relative "linzer/message/wrapper"
 require_relative "linzer/signature"
 require_relative "linzer/key"
 require_relative "linzer/rsa"
@@ -28,11 +29,6 @@ module Linzer
 
   class << self
     include Key::Helper
-    include Response
-
-    def new_request(verb, uri = "/", params = {}, headers = {})
-      Linzer::Request.build(verb, uri, params, headers)
-    end
 
     def verify(pubkey, message, signature, no_older_than: nil)
       Linzer::Verifier.verify(pubkey, message, signature, no_older_than: no_older_than)
@@ -41,5 +37,27 @@ module Linzer
     def sign(key, message, components, options = {})
       Linzer::Signer.sign(key, message, components, options)
     end
+
+    def sign!(request_or_response, **args)
+      message = Message.new(request_or_response)
+      options = {}
+
+      label = args[:label]
+      options[:label] = label if label
+      options.merge!(args.fetch(:params, {}))
+
+      key = args.fetch(:key)
+      signature = Linzer::Signer.sign(key, message, args.fetch(:components), options)
+      message.attach!(signature)
+    end
+
+    def verify!(request_or_response, key: nil, no_older_than: 900)
+      message = Message.new(request_or_response)
+      signature = Signature.build(message.headers.slice("signature", "signature-input"))
+      keyid = signature.parameters["keyid"]
+      raise Linzer::Error, "key not found" if !key && !keyid
+      verify_key = block_given? ? (yield keyid) : key
+      Linzer.verify(verify_key, message, signature, no_older_than: no_older_than)
+    end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: linzer
 version: !ruby/object:Gem::Version
-  version: 0.7.0.beta2
+  version: 0.7.0.beta3
 platform: ruby
 authors:
 - Miguel Landaeta
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openssl
@@ -123,6 +123,40 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.7.0
+- !ruby/object:Gem::Dependency
+  name: forwardable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.3.3
+- !ruby/object:Gem::Dependency
+  name: net-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
 email:
 - miguel@miguel.cc
 executables: []
@@ -148,8 +182,15 @@ files:
 - lib/linzer/key.rb
 - lib/linzer/key/helper.rb
 - lib/linzer/message.rb
-- lib/linzer/request.rb
-- lib/linzer/response.rb
+- lib/linzer/message/adapter.rb
+- lib/linzer/message/adapter/abstract.rb
+- lib/linzer/message/adapter/http_gem/response.rb
+- lib/linzer/message/adapter/net_http/request.rb
+- lib/linzer/message/adapter/net_http/response.rb
+- lib/linzer/message/adapter/rack/common.rb
+- lib/linzer/message/adapter/rack/request.rb
+- lib/linzer/message/adapter/rack/response.rb
+- lib/linzer/message/wrapper.rb
 - lib/linzer/rsa.rb
 - lib/linzer/rsa_pss.rb
 - lib/linzer/signature.rb
@@ -179,7 +220,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.2
 specification_version: 4
 summary: An implementation of HTTP Messages Signatures (RFC9421)
 test_files: []

data/lib/linzer/request.rb

@@ -1,95 +0,0 @@
-# frozen_string_literal: true
-
-module Linzer
-  module Request
-    extend self
-
-    def build(verb, uri = "/", params = {}, headers = {})
-      validate verb, uri, params, headers
-
-      # XXX: to-do: handle rack request params?
-      request_method = Rack.const_get(verb.upcase)
-      args = {
-        "REQUEST_METHOD" => request_method,
-        "PATH_INFO"      => uri.to_str,
-        "rack.input"     => StringIO.new
-      }
-
-      Rack::Request.new(build_rack_env(headers).merge(args))
-    end
-
-    def rack_header_name(field_name)
-      validate_header_name field_name
-
-      rack_name = field_name.upcase.tr("-", "_")
-      case field_name.downcase
-      when "content-type", "content-length"
-        rack_name
-      else
-        "HTTP_#{rack_name}"
-      end
-    end
-
-    def headers(rack_request)
-      rack_request
-        .each_header
-        .to_h
-        .select do |k, _|
-          k.start_with?("HTTP_") || %w[CONTENT_TYPE CONTENT_LENGTH].include?(k)
-        end
-        .transform_keys { |k| k.downcase.tr("_", "-") }
-        .transform_keys do |k|
-          %w[content-type content-length].include?(k) ? k : k.gsub(/^http-/, "")
-        end
-    end
-
-    private
-
-    def validate(verb, uri, params, headers)
-      validate_verb      verb
-      validate_uri       uri
-      validate_arg_hash  headers: headers
-      validate_arg_hash  params:  params
-    end
-
-    def validate_verb(verb)
-      Rack.const_get(verb.upcase)
-    rescue => ex
-      unknown_method = "Unknown/invalid HTTP request method"
-      raise Error.new, unknown_method, cause: ex
-    end
-
-    def validate_uri(uri)
-      uri.to_str
-    rescue => ex
-      invalid_uri = "Invalid URI"
-      raise Error.new, invalid_uri, cause: ex
-    end
-
-    def validate_arg_hash(hsh)
-      arg_name = hsh.keys.first
-      hsh[arg_name].to_hash
-    rescue => ex
-      err_msg = "invalid \"#{arg_name}\" parameter, cannot be converted to hash."
-      raise Error.new, "Cannot build request: #{err_msg}", cause: ex
-    end
-
-    def validate_header_name(name)
-      raise ArgumentError.new, "Blank header name." if name.empty?
-      name.to_str
-    rescue => ex
-      err_msg = "Invalid header name: '#{name}'"
-      raise Error.new, err_msg, cause: ex
-    end
-
-    def build_rack_env(headers)
-      headers
-        .to_hash
-        .transform_values(&:to_s)
-        .transform_keys { |k| k.upcase.tr("-", "_") }
-        .transform_keys do |k|
-          %w[CONTENT_TYPE CONTENT_LENGTH].include?(k) ? k : "HTTP_#{k}"
-        end
-    end
-  end
-end

data/lib/linzer/response.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Linzer
-  module Response
-    def new_response(body = nil, status = 200, headers = {})
-      Rack::Response.new(body, status, headers.transform_values(&:to_s))
-    end
-  end
-end