linzer 0.7.9.beta2 → 0.7.9.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f13471dec9f1ca620ac5fa94faeb2173632bec2aede20fbb1e156988c48fd10d
-  data.tar.gz: 4dffdf98551884ea0a1b11c892ef1cb2ee5cad1fb6234e1d54890feea210a898
+  metadata.gz: d39f9d5f600453197afb744fc030afc2325f40d580540f9fbbca2ba81e0275e2
+  data.tar.gz: 0ab05a81ade047eb116e0527c8647bce22008a04684b6dae5bdd37a9441b0fa8
 SHA512:
-  metadata.gz: 1ca361d6e8dbc9d1960f37f33785a56cb7cd5a22a61d9fbe44228541c5cf54791acc21d9d19b4fb9a078322855776686d42aff86bbc05d4014cc017669375e9a
-  data.tar.gz: 89979f2b5c0e2d2a527cb04e223879f543a26c0cc81ef702ce5c3858c8f241126a38d28aeb9070bacebfbfdf488eae75e5e75f9fd0a242b5e04dfa12c76f6d6d
+  metadata.gz: 52adbd0af86067b700fd60e2666675134bf58a8ed611b60087ecd3c74da64b50f83232271e4a8a4c2af6162558fd880598fb15af6cd201f9621ff4cd976bbdc5
+  data.tar.gz: b351287249fb050bb06bc08a5312b24bf9876dc555fd7c2ee69edbab15e0b43bec5d0cbc3ab852c1766c2eede159a1bd8c6c2ba963558e308b2ec7e73ad469d5

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.7.9.beta3] - 2026-04-27
+
+- Enforce `expires` signature parameter validation in Verifier.
+
+- Add Faraday middleware and adapters for HTTP message signatures.
+
 ## [0.7.9.beta2] - 2026-04-19
 
 - Add support for http gem 6.x while maintaining compatibility with 5.x.

data/README.md

@@ -30,6 +30,18 @@ Or just `gem install linzer`.
 
 ### Quick start
 
+- To sign/verify HTTP requests and responses, see the
+[Signing Requests](#signing-http-requests-and-responses) and
+[Verifying HTTP signatures](#verifying-http-signatures) or
+[Verifying responses (client-side)](#verifying-responses-client-side)
+sections.
+
+- For a more hands-off approach to enforcing request authentication
+  with HTTP signatures in Rack applications (such as Rails),
+  see the examples in the next section.
+
+### Rack middleware
+
 Add the middleware to your Rack application:
 
 ```ruby
@@ -47,9 +59,6 @@ use Rack::Auth::Signature,
 In this example, the middleware requires a valid HTTP Message Signature
 for all endpoints except /login.
 
-To learn how to sign requests, see the
-[Signing Requests](#signing-http-requests-and-responses) section.
-
 #### Using a configuration file
 
 For more complex setups, you can load configuration from a file, e.g.:
@@ -80,10 +89,13 @@ without a valid signature will be rejected.
 
 #### Next steps
 
+- See how to [sign HTTP messages](#signing-http-requests-and-responses)
+or [verify HTTP requests and responses](#verifying-responses-client-side).
+
 - See a full configuration example:
 [examples/sinatra/http-signatures.yml](https://github.com/nomadium/linzer/tree/master/examples/sinatra/http-signatures.yml)
 
-- Browse the middleware implementation for all options:
+- Browse the Rack middleware implementation for all options:
 [lib/rack/auth/signature.rb](https://github.com/nomadium/linzer/tree/master/lib/rack/auth/signature.rb)
 
 - For more specific scenarios and use cases, continue below.
@@ -97,6 +109,7 @@ method, path, headers, etc).
 Choose your client:
 
 - Use the [http gem](https://github.com/httprb/http) → recommended (simplest)
+- Use Faraday and the provided middleware → also recommended (very simple)
 - Use `Net::HTTP` → lower-level control
 - Use `Linzer::HTTP` → quick experiments / debugging
 
@@ -121,6 +134,35 @@ response.body.to_s
 => "protected content..."
 ```
 
+#### Using Faraday
+
+Linzer ships Faraday middleware for signing outbound requests and verifying
+signed responses.
+
+To sign requests:
+
+```ruby
+require "linzer/faraday"
+
+api_url = "https://example.com/api/service"
+components = %w[@target-uri @authority date cache-control]
+signature_params = {alg: "rsa-pss-sha512", keyid: "test-key-rsa-pss",
+                    expires: Time.now.to_i + 300}
+
+conn = Faraday.new(url: api_url) do |builder|
+  builder.headers["Cache-control"] = "no-cache"
+  builder.headers["Date"] = Time.now.httpdate
+  builder.request :http_signature, key: signing_key,
+                                   components: components,
+                                   params: signature_params
+end
+response = conn.post("/task")
+```
+
+This signs the request automatically before dispatch. In this example,
+`Date` and `Cache-Control` are included in the signature to protect
+freshness-related metadata from modification.
+
 #### Using `Net::HTTP` (manual control)
 
 ```ruby
@@ -293,8 +335,8 @@ end
 
 #### Dynamic key lookup
 
-In many cases, the verification key depends on the `keyid` parameter provided in
-the signature.
+In many cases, the verification key depends on the `keyid` parameter
+provided in the signature.
 
 You can supply a block to resolve keys dynamically:
 
@@ -331,14 +373,48 @@ result = Linzer.verify!(response, key: pubkey, no_older_than: 600)
 # => true
 ```
 
+Or if you are using Faraday, response verification can be handled by
+middleware as well:
+
+```ruby
+require "linzer/faraday"
+
+...
+
+conn = Faraday.new(url: api_url) do |builder|
+  builder.response :http_signature, key: verify_key
+end
+response = conn.post("/task")
+
+response.env[:http_signature_verified]
+# => true
+
+response.env[:http_signature]
+# => #<Linzer::Signature ...>
+```
+
+After verification, the middleware stores:
+
+- `env[:http_signature_verified]` — whether verification succeeded
+
+- `env[:http_signature]` — the parsed `Linzer::Signature` object (when valid)
+
+Verification failures can optionally raise instead of returning status;
+see middleware options below.
+
 ### Using a custom HTTP library
 
-If you’re using an HTTP library or framework other than Rack, http gem or
-`Net::HTTP`, you can plug in your own adapter with very little effort.
+If you are using another HTTP library, you may not need a custom Linzer
+adapter at all. Because Linzer integrates with Faraday middleware, you can
+often use Faraday together with the appropriate Faraday adapter for your
+HTTP client of choice.
+
+If you need tighter integration or are not using Faraday, you can also
+implement a native Linzer adapter directly.
 
-In most cases, implementing an adapter just means mapping your library’s
-request/response objects to the small interface Linzer expects,
-then registering it.
+In most cases, implementing an adapter just means mapping your library's
+request/response objects to the small interface Linzer expects, then
+registering it.
 
 To do this:
 
@@ -383,7 +459,7 @@ pubkey = Linzer.new_ed25519_public_key(test_ed25519_key_pub, "some-key-ed25519")
 
 message = Linzer::Message.new(request)
 
-signature = Linzer::Signature.build(message.headers)
+signature = Linzer::Signature.build(request.headers)
 
 Linzer.verify(pubkey, message, signature)
 # => true
@@ -433,6 +509,14 @@ For deeper details or edge cases, the source code and unit tests are also a good
 
 linzer is built in [Continuous Integration](https://github.com/nomadium/linzer/actions/workflows/main.yml) on Ruby 3.0+.
 
+> [!NOTE]
+>
+> Ruby 3.0 is supported and tested in CI, but RSA-based signature algorithms
+> (RSA-PSS and RSA PKCS#1 v1.5) may not work correctly due to its older
+> OpenSSL bindings. If you need RSA algorithms, use Ruby 3.1 or later.
+> Ruby 3.0 has been EOL since March 2024 — users are advised to upgrade
+> to a supported Ruby release.
+
 ## Security
 
 This gem is provided “as is” without any warranties. It has not

data/lib/faraday/http_signature/middleware.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+module Faraday
+  module HttpSignature
+    # Raised when HTTP response signature verification fails in strict mode.
+    #
+    # Inherits from {Faraday::Error} so that standard Faraday error handling
+    # (e.g. +rescue Faraday::Error+) catches verification failures.
+    # The original {Linzer::VerifyError} is preserved as {#wrapped_exception}
+    # and the {Faraday::Response} is available via {#response}.
+    #
+    # @example Catching a verification failure
+    #   begin
+    #     response = conn.get("/")
+    #   rescue Faraday::HttpSignature::VerifyError => e
+    #     e.message            # => "Failed to verify message: Invalid signature."
+    #     e.response           # => the Faraday::Response object
+    #     e.wrapped_exception  # => the original Linzer::VerifyError
+    #   end
+    #
+    # @see Middleware
+    class VerifyError < Faraday::Error; end
+
+    # Raised when HTTP request signature creation fails.
+    #
+    # Inherits from {Faraday::Error} so that standard Faraday error handling
+    # (e.g. +rescue Faraday::Error+) catches verification failures.
+    # The original {Linzer::Error} is preserved as {#wrapped_exception}.
+    #
+    # @example Catching a signing failure
+    #   begin
+    #     response = conn.post("/")
+    #   rescue Faraday::HttpSignature::SigningError => e
+    #     e.message            # => "Failed to sign message: Missing component."
+    #     e.wrapped_exception  # => the original Linzer::Error
+    #   end
+    #
+    # @see Middleware
+    class SigningError < Faraday::Error; end
+
+    # Faraday middleware for HTTP message signing and verification (RFC 9421).
+    #
+    # When registered via +request+, signs outgoing requests (default).
+    # When registered via +response+, verifies incoming response signatures.
+    # When registered via +use+, signs requests by default; pass
+    # +verify_response: true+ to also verify responses.
+    #
+    # == Verification result metadata
+    #
+    # After response verification, the middleware stores results in
+    # +env[:http_signature_verified]+ (+true+ or +false+) and
+    # +env[:http_signature]+ (the {Linzer::Signature} on success).
+    # These are accessible via +response.env[:http_signature_verified]+.
+    #
+    # @example Sign requests
+    #   conn = Faraday.new(url: "https://example.com") do |f|
+    #     f.request :http_signature, key: my_key, components: %w[@method @path]
+    #   end
+    #
+    # @example Verify responses
+    #   conn = Faraday.new(url: "https://example.com") do |f|
+    #     f.response :http_signature, verify_key: server_pubkey
+    #   end
+    #
+    # @example Lenient verification (no exception on failure)
+    #   conn = Faraday.new(url: "https://example.com") do |f|
+    #     f.response :http_signature, verify_key: server_pubkey, strict: false
+    #   end
+    #   response = conn.get("/")
+    #   response.env[:http_signature_verified]  # => true or false
+    #
+    # @see https://datatracker.ietf.org/doc/html/rfc9421 RFC 9421
+    class Middleware < Faraday::Middleware
+      # Default options for the base middleware class (used by +use+
+      # and +request+ registrations). Signs requests, does not verify
+      # responses, strict mode enabled.
+      DEFAULT_OPTIONS = {
+        sign_request:    true,
+        verify_response: false,
+        strict:          true
+      }.freeze
+
+      # Configuration options for the HTTP signature middleware.
+      #
+      # @!attribute [rw] key
+      #   @return [Linzer::Key, nil] generic key used for signing or
+      #     verification when only one mode is active
+      # @!attribute [rw] sign_request
+      #   @return [Boolean] whether to sign outgoing requests
+      #     (defaults to +true+)
+      # @!attribute [rw] sign_key
+      #   @return [Linzer::Key, nil] explicit key for signing; required
+      #     when both signing and verification are enabled
+      # @!attribute [rw] components
+      #   @return [Array<String>] HTTP message components to include in
+      #     the signature (e.g. +["@method", "@path", "content-type"]+)
+      # @!attribute [rw] verify_response
+      #   @return [Boolean] whether to verify incoming response signatures
+      #     (defaults to +false+)
+      # @!attribute [rw] verify_key
+      #   @return [Linzer::Key, nil] explicit key for verification; required
+      #     when both signing and verification are enabled
+      # @!attribute [rw] params
+      #   @return [Hash] additional signature parameters
+      #     (e.g. +{ tag: "my_tag" }+)
+      # @!attribute [rw] strict
+      #   @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)
+        # Returns the generic key.
+        # @return [Linzer::Key, nil]
+        def key
+          self[:key]
+        end
+
+        # Whether outgoing requests should be signed.
+        # Defaults to +true+ (returns +true+ when unset).
+        # @return [Boolean]
+        def sign_request?
+          self[:sign_request] != false
+        end
+
+        # Whether incoming responses should be verified.
+        # Defaults to +false+ (returns +false+ when unset).
+        # @return [Boolean]
+        def verify_response?
+          self[:verify_response]
+        end
+
+        # Whether verification failures should raise an exception.
+        # Defaults to +true+ (returns +true+ when unset).
+        # @return [Boolean]
+        def strict?
+          self[:strict] != false
+        end
+
+        # Returns the list of HTTP message components to sign.
+        # @return [Array<String>]
+        def components
+          Array(self[:components])
+        end
+
+        # Returns additional signature parameters.
+        # @return [Hash]
+        def params
+          Hash(self[:params])
+        end
+      end
+
+      # Creates a new middleware instance.
+      #
+      # Merges class-level {DEFAULT_OPTIONS} with the user-provided options
+      # so that subclasses ({Request}, {Response}) can override defaults.
+      #
+      # @param app [#call] the next middleware or adapter in the stack
+      # @param options [Hash, nil] middleware options
+      # @option options [Linzer::Key] :key generic key for signing or verification
+      # @option options [Linzer::Key] :sign_key explicit signing key
+      # @option options [Linzer::Key] :verify_key explicit verification key
+      # @option options [Array<String>] :components components to sign
+      # @option options [Hash] :params additional signature parameters
+      # @option options [Boolean] :sign_request (+true+) whether to sign requests
+      # @option options [Boolean] :verify_response (+false+) whether to verify responses
+      # @option options [Boolean] :strict (+true+) raise on verification failure
+      def initialize(app, options = nil)
+        super(app)
+        defaults = self.class::DEFAULT_OPTIONS
+        merged = defaults.merge(Hash(options))
+        @options = Options.from(merged)
+      end
+
+      # Signs the outgoing request when {Options#sign_request?} is +true+.
+      #
+      # Resolves the signing key, builds a {Linzer::Message} from the
+      # Faraday environment, generates a signature over the configured
+      # components, and merges the +signature+ and +signature-input+
+      # headers into the request.
+      #
+      # @param env [Faraday::Env] the middleware environment
+      # @return [Faraday::Env, nil] the modified env, or +nil+ if signing
+      #   is disabled
+      # @raise [Linzer::Error] if no valid signing key is available
+      def on_request(env)
+        return unless options.sign_request?
+
+        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)
+        env
+      rescue Linzer::Error => e
+        raise SigningError, e if options.strict?
+      end
+
+      # Verifies the response signature when {Options#verify_response?} is +true+.
+      #
+      # On success, sets +env[:http_signature_verified]+ to +true+ and
+      # +env[:http_signature]+ to the verified {Linzer::Signature}.
+      #
+      # On failure in strict mode (default), raises {VerifyError}.
+      # In lenient mode (+strict: false+), sets
+      # +env[:http_signature_verified]+ to +false+ and allows the response
+      # to continue through the middleware stack.
+      #
+      # @param env [Faraday::Env] the middleware environment
+      # @return [Faraday::Env, nil] the modified env, or +nil+ if verifying
+      #   is disabled
+      # @raise [VerifyError] if verification fails and +strict+ is +true+
+      # @raise [Linzer::Error] if no valid verification key is available
+      def on_complete(env)
+        env[:http_signature_verified] = false
+        return unless options.verify_response?
+
+        key = resolve_verify_key
+        response = ::Faraday::Response.new(env)
+        message = Linzer::Message.new(response)
+        signature = Linzer::Signature.build(response.headers)
+
+        Linzer.verify(key, message, signature)
+        env[:http_signature_verified] = true
+        env[:http_signature] = signature
+        env
+      rescue Linzer::Error => e
+        raise VerifyError.new(e, response: response) if options.strict?
+      end
+
+      private
+
+      # Resolves the key to use for signing requests.
+      #
+      # Prefers {Options#sign_key}. Falls back to the generic {Options#key}
+      # when only one mode (sign or verify) is active. When both modes are
+      # active, the generic key is ambiguous and +sign_key+ must be set
+      # explicitly.
+      #
+      # @return [Linzer::Key] the resolved signing key
+      # @raise [Linzer::Error] if no key is available or the key is invalid
+      def resolve_signing_key
+        key = options.sign_key
+        key ||= options.key unless options.sign_request? && options.verify_response?
+        raise Linzer::Error, "No signing key provided!" if !key
+        raise Linzer::Error, "Invalid key!" if !key.is_a?(Linzer::Key)
+
+        key
+      end
+
+      # Resolves the key to use for verifying response signatures.
+      #
+      # Prefers {Options#verify_key}. Falls back to the generic {Options#key}
+      # when only one mode (sign or verify) is active. When both modes are
+      # active, the generic key is ambiguous and +verify_key+ must be set
+      # explicitly.
+      #
+      # @return [Linzer::Key] the resolved verification key
+      # @raise [Linzer::Error] if no key is available or the key is invalid
+      def resolve_verify_key
+        key = options.verify_key
+        key ||= options.key unless options.sign_request? && options.verify_response?
+        raise Linzer::Error, "No verification key provided!" if !key
+        raise Linzer::Error, "Invalid key!" if !key.is_a?(Linzer::Key)
+
+        key
+      end
+
+      # Subclass registered under {Faraday::Request}.
+      #
+      # Inherits the base {DEFAULT_OPTIONS} which sign requests by default
+      # and do not verify responses.
+      #
+      # @example
+      #   f.request :http_signature, key: my_key, components: %w[@method @path]
+      class Request < self
+      end
+
+      # Subclass registered under {Faraday::Response}.
+      #
+      # Overrides {DEFAULT_OPTIONS} to verify responses by default and
+      # not sign requests.
+      #
+      # @example
+      #   f.response :http_signature, verify_key: server_pubkey
+      class Response < self
+        # Default options for the response subclass. Verifies responses
+        # and does not sign requests.
+        DEFAULT_OPTIONS = {
+          sign_request:    false,
+          verify_response: true,
+          strict:          true
+        }.freeze
+      end
+    end
+  end
+end

data/lib/faraday/http_signature.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "faraday"
+require_relative "http_signature/middleware"
+
+module Faraday
+  # Faraday middleware for signing and verifying HTTP messages
+  # as defined in RFC 9421.
+  #
+  # Three registration points are provided so the middleware can be added
+  # via +request+, +response+ or +use+, each with appropriate defaults:
+  #
+  # @example Sign outgoing requests
+  #   conn = Faraday.new(url: "https://example.com") do |f|
+  #     f.request :http_signature, key: my_key, components: %w[@method @path]
+  #   end
+  #
+  # @example Verify incoming responses
+  #   conn = Faraday.new(url: "https://example.com") do |f|
+  #     f.response :http_signature, verify_key: server_pubkey
+  #   end
+  #
+  # @example Sign requests and verify responses
+  #   conn = Faraday.new(url: "https://example.com") do |f|
+  #     f.use :http_signature, sign_key: my_key, verify_key: server_pubkey,
+  #       verify_response: true, components: %w[@method @path]
+  #   end
+  #
+  # @see Faraday::HttpSignature::Middleware
+  # @see https://datatracker.ietf.org/doc/html/rfc9421 RFC 9421 - HTTP Message Signatures
+  module HttpSignature
+    Faraday::Request.register_middleware(http_signature:    Faraday::HttpSignature::Middleware::Request)
+    Faraday::Response.register_middleware(http_signature:   Faraday::HttpSignature::Middleware::Response)
+    Faraday::Middleware.register_middleware(http_signature: Faraday::HttpSignature::Middleware)
+  end
+end

data/lib/linzer/faraday/utils.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Linzer
+  # Faraday integration for Linzer.
+  #
+  # @see file:lib/linzer/faraday.rb
+  module Faraday
+    # Utility methods for converting Faraday middleware objects into
+    # types compatible with Linzer adapters.
+    module Utils
+      # Creates a {::Faraday::Request} from a middleware environment.
+      #
+      # Builds a minimal request suitable for use with
+      # {Linzer::Message::Adapter::Faraday::Request}, preserving the
+      # original HTTP method, URL, and headers from the environment.
+      #
+      # @param env [::Faraday::Env] the middleware environment
+      # @return [::Faraday::Request] a new request object
+      def self.create_request(env)
+        ::Faraday::Request.create(env.method) do |req|
+          req.params  = ::Faraday::Utils::ParamsHash.new
+          req.headers = ::Faraday::Utils::Headers.new(env.request_headers.dup)
+          req.options = ::Faraday::ConnectionOptions.from(nil).request
+          req.url       env.url
+        end
+      end
+    end
+  end
+end

data/lib/linzer/faraday.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Faraday integration for Linzer.
+#
+# Require this file to automatically register Faraday message adapters
+# and the HTTP signature (RFC 9421) middleware.
+#
+# This sets up:
+# - {Linzer::Message::Adapter::Faraday::Request} for {::Faraday::Request}
+# - {Linzer::Message::Adapter::Faraday::Response} for {::Faraday::Response}
+# - {Faraday::HttpSignature::Middleware} registered as +:http_signature+
+#   on +Faraday::Request+, +Faraday::Response+ and +Faraday::Middleware+
+#
+# @example
+#   require "linzer/faraday"
+#
+#   conn = Faraday.new(url: "https://example.com") do |f|
+#     f.request :http_signature, key: my_key, components: %w[@method @path]
+#   end
+
+require "faraday"
+require "linzer"
+require "faraday/http_signature"
+require "linzer/message/adapter/faraday/request"
+require "linzer/message/adapter/faraday/response"
+require "linzer/faraday/utils"
+
+Linzer::Message.register_adapter(Faraday::Request,  Linzer::Message::Adapter::Faraday::Request)
+Linzer::Message.register_adapter(Faraday::Response, Linzer::Message::Adapter::Faraday::Response)

data/lib/linzer/http.rb

@@ -78,6 +78,14 @@ module Linzer
     private
 
     # Executes a signed HTTP request.
+    #
+    # Validates inputs, builds and signs the request, then sends it.
+    #
+    # @param verb [Symbol] the HTTP method (e.g. +:get+, +:post+)
+    # @param uri [String] the request URI
+    # @param options [Hash] request options
+    # @return [Net::HTTPResponse] the response
+    # @raise [Linzer::Error] if the verb or key is invalid
     def request(verb, uri, options = {})
       validate_verb(verb)
 
@@ -100,10 +108,16 @@ module Linzer
       do_request(http, uri, verb, options[:data], signature, headers)
     end
 
+    # Returns the default covered components for signing.
+    # @return [Array<String>]
     def default_components
       Linzer::Options::DEFAULT[:covered_components]
     end
 
+    # Validates that the HTTP verb is recognized.
+    #
+    # @param verb [Symbol] the HTTP method
+    # @raise [Linzer::Error] if the verb is unknown
     def validate_verb(verb)
       method_name = verb.to_s.upcase
       if !known_http_methods.include?(method_name)
@@ -111,17 +125,32 @@ module Linzer
       end
     end
 
+    # Validates that the signing key is present and usable.
+    #
+    # @param key [Linzer::Key] the signing key
+    # @return [Linzer::Key] the validated key
+    # @raise [Linzer::Error] if the key is nil or does not respond to +#sign+
     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
 
+    # Builds request headers, adding a default User-Agent if not present.
+    #
+    # @param headers [Hash] user-provided headers
+    # @return [Hash] headers with User-Agent ensured
     def build_headers(headers)
       return headers if headers.transform_keys(&:downcase).key?("user-agent")
       headers.merge({"user-agent" => "Linzer/#{Linzer::VERSION}"})
     end
 
+    # Builds a Net::HTTP request object for the given method and URI.
+    #
+    # @param method [Symbol] the HTTP method
+    # @param uri [String] the request URI
+    # @param headers [Hash] request headers to set
+    # @return [Net::HTTPRequest] the constructed request
     def build_request(method, uri, headers)
       request_class = Net::HTTP.const_get(method.to_s.capitalize)
       request = request_class.new(URI(uri))
@@ -129,7 +158,10 @@ module Linzer
       request
     end
 
-    # Determines if the HTTP method typically has a request body.
+    # Checks if the HTTP method typically carries a request body.
+    #
+    # @param verb [Symbol] the HTTP method
+    # @return [Boolean] +true+ for POST, PUT, PATCH, and WebDAV write methods
     def with_body?(verb)
       # common HTTP
       return false if %i[get head options trace delete].include?(verb)
@@ -142,6 +174,16 @@ module Linzer
       true
     end
 
+    # Sends the HTTP request with the signature headers attached.
+    #
+    # @param http [Net::HTTP] the HTTP connection
+    # @param uri [String] the request URI
+    # @param verb [Symbol] the HTTP method
+    # @param data [String, nil] the request body
+    # @param signature [Linzer::Signature] the generated signature
+    # @param headers [Hash] request headers
+    # @return [Net::HTTPResponse] the response
+    # @raise [Linzer::Error] if a body is required but not provided
     def do_request(http, uri, verb, data, signature, headers)
       if with_body?(verb)
         if !data