linzer 0.7.0.beta2 → 0.7.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd7b5e233ec42d94c7040f774097c612850eef9c5795a2c8d3251bc618c8df5f
-  data.tar.gz: 53cc818e2fc68fe1f6b3c89414a5b0d2393e1b8cfa8e4c9f3ba9076ce537f81c
+  metadata.gz: 5cfa8303792377ef25d8a81300b1e22c2e6593237436e152ec04e99176eea1f7
+  data.tar.gz: e2f89b7b4d771a9912000961862bf77cda5ccf2caf40a3906394afa1b1595adc
 SHA512:
-  metadata.gz: 93e5fb0d4fd0cd534691102a02efa8ae14589d12ee3636f86d10d19e57104b1bb122f950c9191c5fb40264fc453a31d33aa1369fac0fe34451e74108ce9c6a5c
-  data.tar.gz: e5b12b53e46f7958c560cb579111c14eab85da6a047effcdb599d39f955fe38b89175faef1937a963890c8d8254763c54314ea95c4eff70815fc0c0b8c396551
+  metadata.gz: 3881ae41ea932485f39838bba647f60fce089f740dabe7db7e01d34c368ebaf85ec71788d997d64d9cc662811dd703babd62300f7d02c6a21072c1dafbb45ee5
+  data.tar.gz: 7a9589f81440612f7e3bc959973aa947614c132f67db247e043f911d1653c7621c376ade8005181fa6fc4814e542ec82556bf79ec5f2b0d3ede739d48d4ffeb0

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.7.0.beta4] - 2025-05-17
+
+- Provide integration with http.rb gem to allow signing outgoing HTTP requests.
+- Add simple HTTP client module.
+
+## [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,65 @@ 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
+There are several options:
 
-headers = {
-  "date" => "Fri, 23 Feb 2024 17:57:23 GMT",
-  "x-custom-header" => "foo"
-}
+#### If you are using http gem:
 
-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>
+```ruby
+# first require http signatures feature class ready to be used with http gem:
+require "linzer/http/signature_feature"
 
-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>>
+key = Linzer.generate_ed25519_key # generate a new key pair
+# => #<Linzer::Ed25519::Key:0x00000fe13e9bd208
+# or load an existing key with:
+# key = Linzer.new_ed25519_key(IO.read("key"), "mykeyid")
+
+# then send the request:
+url = "https://example.org/api"
+response = HTTP.headers(date: Time.now.to_s, foo: "bar")
+               .use(http_signature: {key: key} # <--- covered components
+               .get(url) # and signature params can also be customized on the client
+=> #<HTTP::Response/1.1 200 OK {"Content-Type" => ...
+response.body.to_s
+=> "protected content..."
+```
 
-fields = %w[date x-custom-header @method @path]
+#### If you are using plain old Net::HTTP:
 
-signature = Linzer.sign(key, message, fields)
-# => #<Linzer::Signature:0x0000000111f77ad0 ...
+```ruby
+key = Linzer.generate_ed25519_key
+# => #<Linzer::Ed25519::Key:0x00000fe13e9bd208
 
-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:
+Then you can submit the signed request with Net::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 +150,144 @@ response = http.post("/some_uri", "data", headers.merge(signature.to_h))
 # => #<Net::HTTPOK 200 OK readbody=true>
 ```
 
-### To verify a valid signature:
+#### Or you can also use the simple HTTP client bundled with this library:
+
+(This client is probably not suitable for production use but could be useful
+enough to get started. It's build on top of Net::HTTP.)
+
+```ruby
+key = Linzer.generate_rsa_pss_sha512_key(4096)
+uri = URI("https://example.org/api/task")
+headers = {"date" => Time.now.to_s}
+response =
+  Linzer::HTTP
+    .post("http://httpbin.org/headers",
+          data: "foo",
+          debug: true,
+          key: key,
+          headers: headers)
+...
+=> #<Net::HTTPOK 200 OK readbody=true>
+```
+
+### 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, Linzer::Message::Adapter::HTTPGem::Response)
+# Linzer::Message.register_adapter(HTTP::Response, MyOwnResponseAdapter) # or use your own adapter
+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 +296,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 +313,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/http/bootstrap.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Linzer
+  module HTTP
+    module Bootstrap
+      class << self
+        def require_dependencies
+          require "http"
+          require_relative "../message/adapter/http_gem/request"
+        end
+
+        def load_dependencies
+          require_dependencies
+        rescue LoadError
+          msg = "http gem is required to be installed to use this feature."
+          raise Linzer::Error, msg
+        end
+      end
+    end
+  end
+end

data/lib/linzer/http/signature_feature.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require_relative "bootstrap"
+
+module Linzer
+  module HTTP
+    class << self
+      def register_adapter
+        request_class = ::HTTP::Request
+        adapter_class = Linzer::Message::Adapter::HTTPGem::Request
+        Linzer::Message.register_adapter(request_class, adapter_class)
+      end
+    end
+
+    Bootstrap.load_dependencies
+    register_adapter
+
+    class SignatureFeature < ::HTTP::Feature
+      def initialize(key:, params: {}, covered_components: default_components)
+        @fields = Array(covered_components)
+        @key    = validate_key(key)
+        @params = Hash(params)
+      end
+
+      attr_reader :fields, :params
+
+      def wrap_request(request)
+        message   = Linzer::Message.new(request)
+        signature = Linzer.sign(key, message, fields, **params)
+        request.headers.merge!(signature.to_h)
+        request
+      end
+
+      def default_covered_components
+        Linzer::Options::DEFAULT[:covered_components]
+      end
+
+      alias_method :default_components, :default_covered_components
+
+      private
+
+      attr_reader :key
+
+      def validate_key(key)
+        raise ::HTTP::Error, "Key can not be nil!"    if !key
+        raise ::HTTP::Error, "Key object is invalid!" if !key.respond_to?(:sign)
+        key
+      end
+
+      ::HTTP::Options.register_feature(:http_signature, self)
+    end
+  end
+end

data/lib/linzer/http.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+require "net/http"
+
+module Linzer
+  module HTTP
+    extend self
+
+    def self.known_http_methods
+      Net::HTTP
+        .constants
+        .map    { |const| Net::HTTP.const_get(const) }
+        .select { |klass| klass.is_a?(Class) && klass.const_defined?(:METHOD) }
+        .map    { |klass| klass::METHOD }
+        .freeze
+    end
+
+    known_http_methods.each do |http_method|  # e.g.:
+      method = http_method.downcase.to_sym    #
+      define_method(method) do |uri, options| # def post(uri, **options)
+        options ||= {}                        #   request :post, uri, options
+        request method, uri, options          # end
+      end
+    end
+
+    private
+
+    def request(verb, uri, options = {})
+      validate_verb(verb)
+
+      key = options[:key]
+      validate_key(key)
+
+      req_uri = URI(uri)
+      http = Net::HTTP.new(req_uri.host, req_uri.port)
+      http.set_debug_output($stderr) if options[:debug]
+
+      headers    = build_headers(options[:headers] || {})
+      request    = build_request(verb, uri, headers)
+      message    = Linzer::Message.new(request)
+      components = options[:covered_components] || default_components
+      params     = options[:params] || {}
+      signature  = Linzer.sign(key, message, components, **params)
+
+      do_request(http, uri, verb, options[:data], signature, headers)
+    end
+
+    def default_components
+      Linzer::Options::DEFAULT[:covered_components]
+    end
+
+    def validate_verb(verb)
+      method_name = verb.to_s.upcase
+      if !known_http_methods.include?(method_name)
+        raise Linzer::Error, "Unknown/unsupported HTTP method: '#{method_name}'"
+      end
+    end
+
+    def validate_key(key)
+      raise Linzer::Error, "Key can not be nil!"    if !key
+      raise Linzer::Error, "Key object is invalid!" if !key.respond_to?(:sign)
+      key
+    end
+
+    def build_headers(headers)
+      headers.merge({"user-agent" => "Linzer/#{Linzer::VERSION}"})
+    end
+
+    def build_request(method, uri, headers)
+      request_class = Net::HTTP.const_get(method.to_s.capitalize)
+      request = request_class.new(URI(uri))
+      headers.map { |k, v| request[k] = v }
+      request
+    end
+
+    def with_body?(verb)
+      # common HTTP
+      return false if %i[get head options trace delete].include?(verb)
+      # WebDAV
+      return false if %i[copy move].include?(verb)
+
+      # everything else that could have a body:
+      # common HTTP: post, put, patch
+      # WebDAV:      lock, unlock, mkcol, propfind, proppatch
+      true
+    end
+
+    def do_request(http, uri, verb, data, signature, headers)
+      if with_body?(verb)
+        if !data
+          missed_body = "Missing request body on HTTP request: '#{verb.upcase}'"
+          raise Linzer::Error, missed_body
+        end
+        http.public_send(verb, uri, data, headers.merge(signature.to_h))
+      else
+        http.public_send(verb, uri,       headers.merge(signature.to_h))
+      end
+    end
+  end
+end

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/request.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      module HTTPGem
+        class Request < Linzer::Message::Adapter::NetHTTP::Request
+          def headers
+            @operation.headers.to_h
+          end
+
+          private
+
+          def derived(name)
+            return @operation.verb.to_s.upcase if name.value == :method
+            super
+          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