linzer 0.7.0.beta3 → 0.7.0.beta4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65ccb6f89aab47730e202a8ad376b2ceb310213b2a140d194b2b6fd285aa710f
-  data.tar.gz: 485efd259e353048041528c38f0072945592cfe6f8d4c4e6ea20af5546e6cb94
+  metadata.gz: 5cfa8303792377ef25d8a81300b1e22c2e6593237436e152ec04e99176eea1f7
+  data.tar.gz: e2f89b7b4d771a9912000961862bf77cda5ccf2caf40a3906394afa1b1595adc
 SHA512:
-  metadata.gz: a01a27867e6dd628365268f1106880b7f61ad80b4d314ea336e21e4f1a4edbb17394d0c7da4f23256566e34a6acb2e6eec54680461141d917189a37219d3c84e
-  data.tar.gz: 2efef6b1fcad53964e1f54c8f1453b2ad3aa481ca98960ada2e735439d0736624118a99ab58d1f73fdef517f9802e1453215e17bfc660e56dae81cd5b044769d
+  metadata.gz: 3881ae41ea932485f39838bba647f60fce089f740dabe7db7e01d34c368ebaf85ec71788d997d64d9cc662811dd703babd62300f7d02c6a21072c1dafbb45ee5
+  data.tar.gz: 7a9589f81440612f7e3bc959973aa947614c132f67db247e043f911d1653c7621c376ade8005181fa6fc4814e542ec82556bf79ec5f2b0d3ede739d48d4ffeb0

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [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

data/README.md

@@ -60,6 +60,31 @@ To learn about more specific scenarios or use cases, keep reading on below.
 
 ### To sign a HTTP request:
 
+There are several options:
+
+#### If you are using http gem:
+
+```ruby
+# first require http signatures feature class ready to be used with http gem:
+require "linzer/http/signature_feature"
+
+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..."
+```
+
+#### If you are using plain old Net::HTTP:
+
 ```ruby
 key = Linzer.generate_ed25519_key
 # => #<Linzer::Ed25519::Key:0x00000fe13e9bd208
@@ -84,7 +109,7 @@ request["signature-input"]
 # => "sig1=(\"@method\" \"@request-target\" \"date\" ..."}
 ```
 
-### Use the signed request with an HTTP client:
+Then you can submit the signed request with Net::HTTP client:
 
 ```ruby
 require "net/http"
@@ -125,6 +150,26 @@ response = http.request(request)
 # => #<Net::HTTPOK 200 OK readbody=true>
 ```
 
+#### 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
@@ -220,7 +265,8 @@ 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)
+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"]

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

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Linzer
+  module Options
+    DEFAULT = {
+      covered_components: %w[@method @request-target @authority date]
+    }.freeze
+  end
+end

data/lib/linzer/version.rb

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

data/lib/linzer.rb

@@ -9,6 +9,7 @@ require "net/http"
 
 require_relative "linzer/version"
 require_relative "linzer/common"
+require_relative "linzer/options"
 require_relative "linzer/message"
 require_relative "linzer/message/adapter"
 require_relative "linzer/message/wrapper"
@@ -22,6 +23,7 @@ require_relative "linzer/ecdsa"
 require_relative "linzer/key/helper"
 require_relative "linzer/signer"
 require_relative "linzer/verifier"
+require_relative "linzer/http"
 require_relative "rack/auth/signature"
 
 module Linzer

data/lib/rack/auth/signature/helpers.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "yaml"
 
 module Rack

data/lib/rack/auth/signature.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "linzer"
 require "logger"
 require_relative "signature/helpers"

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: linzer
 version: !ruby/object:Gem::Version
-  version: 0.7.0.beta3
+  version: 0.7.0.beta4
 platform: ruby
 authors:
 - Miguel Landaeta
 bindir: exe
 cert_chain: []
-date: 2025-05-06 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openssl
@@ -157,6 +157,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.6.0
+- !ruby/object:Gem::Dependency
+  name: cgi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.4.2
 email:
 - miguel@miguel.cc
 executables: []
@@ -179,11 +193,15 @@ files:
 - lib/linzer/ecdsa.rb
 - lib/linzer/ed25519.rb
 - lib/linzer/hmac.rb
+- lib/linzer/http.rb
+- lib/linzer/http/bootstrap.rb
+- lib/linzer/http/signature_feature.rb
 - lib/linzer/key.rb
 - lib/linzer/key/helper.rb
 - lib/linzer/message.rb
 - lib/linzer/message/adapter.rb
 - lib/linzer/message/adapter/abstract.rb
+- lib/linzer/message/adapter/http_gem/request.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
@@ -191,6 +209,7 @@ files:
 - lib/linzer/message/adapter/rack/request.rb
 - lib/linzer/message/adapter/rack/response.rb
 - lib/linzer/message/wrapper.rb
+- lib/linzer/options.rb
 - lib/linzer/rsa.rb
 - lib/linzer/rsa_pss.rb
 - lib/linzer/signature.rb
@@ -220,7 +239,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.8
 specification_version: 4
 summary: An implementation of HTTP Messages Signatures (RFC9421)
 test_files: []