linzer 0.7.9.beta2 → 0.7.9.beta3

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

@@ -96,7 +96,10 @@ module Linzer
         private
 
         # Parses a field name string into a FieldId.
-        # @return [FieldId, nil] The parsed identifier, or nil if invalid
+        #
+        # @param field_name [String] the component identifier string
+        # @return [FieldId, nil] the parsed identifier, or +nil+ if invalid
+        # @raise [Error] if +@status+ is used in a request message
         def parse_field_name(field_name)
           field_id  = FieldId.new(field_name: field_name)
           component = field_id.item
@@ -117,8 +120,12 @@ module Linzer
           raise Linzer::Error, msg unless message.request?
         end
 
-        # Validates component identifier parameters.
-        # @return [Object, nil] The validated name, or nil if invalid
+        # Validates component identifier parameters against RFC 9421 rules.
+        #
+        # @param name [Starry::Item] the parsed component identifier
+        # @param method [Symbol] +:derived+ or +:field+
+        # @return [Starry::Item, nil] the validated name, or +nil+ if
+        #   the parameter combination is invalid
         def validate_parameters(name, method)
           has_unknown = name.parameters.any? { |p, _| !KNOWN_PARAMETERS.include?(p) }
           return nil if has_unknown
@@ -149,6 +156,13 @@ module Linzer
         private_constant :KNOWN_PARAMETERS
 
         # Retrieves a component value with parameter processing.
+        #
+        # Handles +;req+, +;sf+, +;key+, and +;bs+ parameters by
+        # delegating to the corresponding helper methods.
+        #
+        # @param name [Starry::Item] the parsed component identifier
+        # @param method [Symbol] +:derived+ or +:field+
+        # @return [String, Integer, nil] the component value
         def retrieve(name, method)
           if !name.parameters.empty?
             valid_params = validate_parameters(name, method)
@@ -176,6 +190,10 @@ module Linzer
         end
 
         # Processes a structured field value with optional key extraction.
+        #
+        # @param value [String] the raw header value to parse as a dictionary
+        # @param key [String, nil] if present, extracts a single dictionary member
+        # @return [String] the serialized structured field value
         # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-2.1.1
         def sf(value, key = nil)
           dict = Starry.parse_dictionary(value)
@@ -188,19 +206,31 @@ module Linzer
           end
         end
 
-        # Binary-wraps a field value.
+        # Binary-wraps a field value as a byte sequence.
+        #
+        # @param value [String] the header value to wrap
+        # @return [String] the serialized byte sequence
         # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-2.1.3
         def bs(value)
           Starry.serialize(value.encode(Encoding::ASCII_8BIT))
         end
 
         # Retrieves a trailer field value.
+        #
         # @abstract Subclasses should implement if trailer support is needed.
+        # @param trailer [Object] the trailer field identifier
+        # @return [String, nil] the trailer value
+        # @raise [Error] always, since no built-in adapters support trailers
         def tr(trailer)
           raise Error, "Sub-classes are required to implement this method!"
         end
 
-        # Retrieves a field from the attached request.
+        # Retrieves a field from the attached request (for +;req+ parameter).
+        #
+        # @param field [Starry::Item] the component identifier
+        # @param method [Symbol] +:derived+ or +:field+
+        # @return [String, nil] the value from the attached request, or
+        #   +nil+ if no request is attached
         def req(field, method)
           attached_request? ? @attached_request[String(field)] : nil
         end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      module Faraday
+        # Adapter for {::Faraday::Request} objects from the faraday gem.
+        #
+        # Extends the generic request adapter with faraday-specific
+        # derived component retrieval, field lookup, and URI handling.
+        #
+        # @note Not loaded automatically to avoid making faraday a hard
+        #   dependency. Require +"linzer/faraday"+ to register this adapter.
+        #
+        # @see Generic::Request
+        # @see https://github.com/lostisland/faraday faraday gem
+        class Request < Generic::Request
+          private
+
+          # Resolves a derived component value from the request.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the derived value, or +nil+ if unknown
+          def derived(name)
+            url = @operation.path
+            case name.value
+            when "@method"         then @operation.http_method.to_s.upcase
+            when "@target-uri"     then uri.to_s
+            when "@authority"      then url.authority.downcase
+            when "@scheme"         then url.scheme.downcase
+            when "@request-target" then uri.request_uri
+            when "@path"           then url.path
+            when "@query"          then "?%s" % String(uri_query)
+            when "@query-param"    then query_param(uri_query, name)
+            end
+          end
+
+          # Builds the full URI including query parameters.
+          #
+          # @return [URI] the complete request URI with encoded query string
+          def uri
+            uri = @operation.path.dup
+            uri.query = URI.encode_www_form(@operation.params)
+            uri
+          end
+
+          # Returns the raw query string from the request URI.
+          #
+          # Prefers the raw query string from the URI when available,
+          # as Faraday normalises percent-encoding when parsing params
+          # (e.g. +%2D+ becomes +-+), which would break signature
+          # verification.
+          #
+          # @return [String, nil] the raw query string
+          def uri_query
+            url = @operation.path
+            url.query || uri.query
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Linzer
+  class Message
+    module Adapter
+      module Faraday
+        # Adapter for {::Faraday::Response} objects from the faraday gem.
+        #
+        # Extends the generic response adapter with faraday-specific
+        # derived component retrieval (e.g. +@status+) and header
+        # attachment.
+        #
+        # @note Not loaded automatically to avoid making faraday a hard
+        #   dependency. Require +"linzer/faraday"+ to register this adapter.
+        #
+        # @see Generic::Response
+        # @see https://github.com/lostisland/faraday faraday gem
+        class Response < Generic::Response
+          # Attaches a signature to the underlying response headers.
+          #
+          # @param signature [Linzer::Signature] the signature to attach
+          # @return [::Faraday::Response] the underlying response object
+          def attach!(signature)
+            signature.to_h.each { |h, v| @operation.headers[h] = v }
+            @operation
+          end
+
+          private
+
+          # Resolves a derived component value from the response.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [Integer, nil] the HTTP status code for +@status+,
+          #   or +nil+ if the component is unknown
+          def derived(name)
+            case name.value
+            when "@status" then @operation.status.to_i
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -51,31 +51,35 @@ module Linzer
           private
 
           def derived(name)
-            unimplemented_method = 'Derived field "@method" lookup is not implemented!'
+            unimplemented_method = 'Derived field "%s" lookup is not implemented!'
+
+            uri = @operation.uri rescue nil
+            raise Error, unimplemented_method % name.value if uri.nil?
+
             case name.value
-            when "@method"         then raise Error, unimplemented_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)
+            when "@method"         then raise Error, unimplemented_method % name.value
+            when "@target-uri"     then uri.to_s
+            when "@authority"      then uri.authority.downcase
+            when "@scheme"         then uri.scheme.downcase
+            when "@request-target" then uri.request_uri
+            when "@path"           then uri.path
+            when "@query"          then "?%s" % String(uri.query)
+            when "@query-param"    then query_param(uri.query, name)
             end
           end
 
-          def query_param(name)
+          def query_param(uri_query, 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)
+            params = CGI.parse(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 = header(name.value.to_s)
             value.dup&.strip
           end
         end

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

@@ -30,6 +30,11 @@ module Linzer
 
           private
 
+          # Retrieves an HTTP field value from the request or response headers.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the stripped header value, or +nil+ if the
+          #   field has a +tr+ (trailer) parameter or is not present
           def field(name)
             has_tr = name.parameters["tr"]
             return nil if has_tr # XXX: is there a library actually supporting trailers?

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

@@ -15,6 +15,14 @@ module Linzer
 
           private
 
+          # Resolves a derived component value from the request.
+          #
+          # Overrides the generic implementation for http.rb-specific
+          # accessor methods: +uri.host+ for +@authority+ and
+          # +verb+ for +@method+.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the derived value
           def derived(name)
             return @operation.uri.host         if name.value == "@authority"
             return @operation.verb.to_s.upcase if name.value == "@method"

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

@@ -19,6 +19,13 @@ module Linzer
 
           private
 
+          # Resolves a derived component value from the response.
+          #
+          # Uses +HTTP::Response#status+ converted to Integer for
+          # the +@status+ component.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [Integer, nil] the HTTP status code, or +nil+ if unknown
           def derived(name)
             case name.value
             when "@status" then @operation.status.to_i

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

@@ -14,6 +14,14 @@ module Linzer
         class Request < Generic::Request
           private
 
+          # Resolves a derived component value from the request.
+          #
+          # Overrides the generic implementation to use
+          # +Net::HTTPRequest#method+ for the +@method+ component,
+          # which returns the HTTP verb as an uppercase string.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the derived value
           def derived(name)
             return @operation.method if name.value == "@method"
             super

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

@@ -11,6 +11,13 @@ module Linzer
         class Response < Generic::Response
           private
 
+          # Resolves a derived component value from the response.
+          #
+          # Uses +Net::HTTPResponse#code+ (a String) converted to Integer
+          # for the +@status+ component.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [Integer, nil] the HTTP status code, or +nil+ if unknown
           def derived(name)
             case name.value
             when "@status" then @operation.code.to_i

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

@@ -24,11 +24,19 @@ module Linzer
 
           private
 
+          # Validates that the operation is exclusively a request or response.
+          # @raise [Error] if the operation is both or neither
           def validate
             msg = "Message instance must be an HTTP request or response"
             raise Error.new msg if response? == request?
           end
 
+          # Validates that a header name is non-empty.
+          #
+          # @param name [String] the header name
+          # @return [String] the validated header name
+          # @raise [ArgumentError] if the name is blank
+          # @raise [Linzer::Error] if the name is otherwise invalid
           def validate_header_name(name)
             raise ArgumentError.new, "Blank header name." if name.empty?
             name.to_str
@@ -40,6 +48,13 @@ module Linzer
             # :nocov:
           end
 
+          # Converts an HTTP header name to Rack's environment key format.
+          #
+          # Rack stores headers as uppercase with underscores and an +HTTP_+
+          # prefix, except for +Content-Type+ and +Content-Length+.
+          #
+          # @param field_name [String] the HTTP header name (e.g. +"content-type"+)
+          # @return [String] the Rack env key (e.g. +"CONTENT_TYPE"+ or +"HTTP_ACCEPT"+)
           def rack_header_name(field_name)
             validate_header_name field_name
 
@@ -52,6 +67,10 @@ module Linzer
             end
           end
 
+          # Resolves a derived component value from the Rack request/response.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the derived value, or +nil+ if unknown
           def derived(name)
             method = DERIVED_COMPONENT[name.value]
 
@@ -64,6 +83,11 @@ module Linzer
             value || derive(@operation, method)
           end
 
+          # Retrieves an HTTP field value from the Rack request or response.
+          #
+          # @param name [Starry::Item] the parsed component identifier
+          # @return [String, nil] the stripped header value, or +nil+ if the
+          #   field has a +tr+ (trailer) parameter or is not present
           def field(name)
             has_tr = name.parameters["tr"]
             return nil if has_tr
@@ -79,6 +103,14 @@ module Linzer
             field_value.dup&.strip
           end
 
+          # Invokes a method on the Rack operation to extract a derived value.
+          #
+          # Applies post-processing for +@query+ (prepends +?+) and
+          # +@authority+/+@scheme+ (downcases).
+          #
+          # @param operation [Rack::Request, Rack::Response] the Rack object
+          # @param method [Symbol] the method to call
+          # @return [String, nil] the derived value
           def derive(operation, method)
             return nil unless operation.respond_to?(method)
             value = operation.public_send(method)
@@ -87,6 +119,11 @@ module Linzer
             value
           end
 
+          # Extracts a single query parameter value by name.
+          #
+          # @param name [Starry::Item] the component with a +name+ parameter
+          # @return [String, nil] the percent-encoded parameter value, or
+          #   +nil+ if the parameter is missing or not found
           def query_param(name)
             param_name = name.parameters["name"]
             return nil if !param_name

data/lib/linzer/message/field/parser.rb

@@ -39,6 +39,14 @@ module Linzer
 
           private
 
+          # Parses an unserialized component identifier with parameters.
+          #
+          # Splits on +;+ to separate the field name from parameters,
+          # then serializes the field name and collects parameters.
+          #
+          # @param field_name [String] e.g. +"content-type;bs"+ or
+          #   +"example-dict;key=\"a\""+
+          # @return [Starry::Item] the parsed item with parameters
           def parse_unserialized_input(field_name)
             field, *raw_params = field_name.split(";")
             item               = Starry.parse_item(Starry.serialize(field))
@@ -46,6 +54,13 @@ module Linzer
             item
           end
 
+          # Parses raw parameter strings into a merged Hash.
+          #
+          # Handles both boolean parameters (+";bs"+ → +{"bs" => true}+)
+          # and key-value parameters (+";key=\"a\""+ → +{"key" => "a"}+).
+          #
+          # @param str [Array<String>] raw parameter strings
+          # @return [Hash] merged parameter hash
           def collect_parameters(str)
             params = str.map do |param|
               if (tokens = param.split("=")) == [param] # e.g.: ";bs"

data/lib/linzer/message/wrapper.rb

@@ -48,8 +48,14 @@ module Linzer
 
         attr_reader :adapters
 
-        # Finds an adapter by checking if operation inherits from a known class.
-        # This allows subclasses of Net::HTTPRequest etc. to work automatically.
+        # Finds an adapter by checking the operation's ancestry.
+        #
+        # This allows subclasses of registered classes (e.g.
+        # +Net::HTTP::Get < Net::HTTPRequest+) to use the parent's adapter
+        # without explicit registration.
+        #
+        # @param operation [Object] the HTTP message object
+        # @return [Class, nil] the adapter class, or +nil+ if no ancestor matches
         def find_ancestor(operation)
           adapters
             .select { |klz, adpt| operation.is_a? klz }
@@ -57,6 +63,10 @@ module Linzer
             .first
         end
 
+        # Raises an error for unsupported HTTP message types.
+        #
+        # @param operation [Object] the unsupported HTTP message
+        # @raise [Linzer::Error] with a message suggesting +register_adapter+
         def fail_with_unsupported(operation)
           err_msg = <<~EOM
             Unknown/unsupported HTTP message class: '#{operation.class}'!

data/lib/linzer/signature.rb

@@ -102,6 +102,26 @@ module Linzer
       (Time.now.to_i - created) > seconds
     end
 
+    # Checks if the signature has expired based on the `expires` parameter.
+    #
+    # If the `expires` parameter is not present, the signature is considered
+    # not expired (returns false). If the parameter is present but not a valid
+    # integer, an error is raised.
+    #
+    # @return [Boolean] true if the signature has expired
+    # @raise [Error] If the `expires` parameter is not a valid integer
+    #
+    # @example Check if a signature has expired
+    #   signature.expired?  # => true or false
+    #
+    # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-2.3 RFC 9421 Section 2.3
+    def expired?
+      return false if !parameters.key?("expires")
+      Time.now.to_i >= Integer(parameters["expires"])
+    rescue ArgumentError, TypeError
+      raise Error.new "Signature has a non-integer `expires` parameter"
+    end
+
     # Converts the signature to HTTP header format.
     #
     # Returns a hash suitable for setting as HTTP headers on a request or

data/lib/linzer/verifier.rb

@@ -23,6 +23,7 @@ module Linzer
       # - All covered components exist in the message
       # - The signature base matches what was signed
       # - The cryptographic signature is valid for the public key
+      # - The signature has not expired (if `expires` parameter is present)
       # - The signature is not older than `no_older_than` (if specified)
       #
       # @param key [Linzer::Key] The public key to verify with. Must respond to
@@ -85,6 +86,13 @@ module Linzer
           raise VerifyError, ex.message, cause: ex
         end
 
+        begin
+          exp_sig_msg = "Signature has expired or is invalid"
+          raise VerifyError, exp_sig_msg if signature.expired?
+        rescue Error => ex
+          raise VerifyError, ex.message, cause: ex
+        end
+
         return unless no_older_than
         old_sig_msg = "Signature created more than #{no_older_than} seconds ago"
         begin

data/lib/linzer/version.rb

@@ -3,5 +3,5 @@
 module Linzer
   # Current version of the Linzer gem.
   # @return [String]
-  VERSION = "0.7.9.beta2"
+  VERSION = "0.7.9.beta3"
 end

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

@@ -5,42 +5,82 @@ require "yaml"
 module Rack
   module Auth
     class Signature
+      # Shared helpers for the Rack signature verification middleware.
+      #
+      # Organizes functionality into three sub-modules:
+      # - {Parameters} — validates required signature parameters
+      # - {Configuration} — loads and merges middleware options
+      # - {Key} — resolves verification keys by keyid
+      #
+      # @api private
       module Helpers
+        # Validates the presence of required signature parameters.
+        #
+        # Each method checks whether a specific parameter is required
+        # (per configuration) and, if so, whether it is present and valid
+        # in the current signature.
+        #
+        # @api private
         module Parameters
           private
 
+          # Checks if the +created+ parameter requirement is satisfied.
+          # @return [Boolean] +true+ if not required or present and valid
           def created?
             !options[:signatures][:created_required] || !!Integer(params.fetch("created"))
           end
 
+          # Checks if the +expires+ parameter requirement is satisfied.
+          # @return [Boolean] +true+ if not required or present and not yet expired
           def expires?
             return true if !options[:signatures][:expires_required]
             Integer(params.fetch("expires")) > Time.now.to_i
           end
 
+          # Checks if the +keyid+ parameter requirement is satisfied.
+          # @return [Boolean] +true+ if not required or present
           def keyid?
             !options[:signatures][:keyid_required] || String(params.fetch("keyid"))
           end
 
+          # Checks if the +nonce+ parameter requirement is satisfied.
+          # @return [Boolean] +true+ if not required or present
           def nonce?
             !options[:signatures][:nonce_required] || String(params.fetch("nonce"))
           end
 
+          # Checks if the +alg+ parameter requirement is satisfied.
+          # @return [Boolean] +true+ if not required or present
           def alg?
             !options[:signatures][:alg_required] || String(params.fetch("alg"))
           end
 
+          # Checks if the +tag+ parameter requirement is satisfied.
+          # @return [Boolean] +true+ if not required or present
           def tag?
             !options[:signatures][:tag_required] || String(params.fetch("tag"))
           end
         end
 
+        # Handles loading and merging of middleware configuration.
+        #
+        # Configuration can come from three sources (in order of precedence):
+        # 1. Options passed directly to the middleware constructor
+        # 2. A YAML configuration file (via +:config_path+)
+        # 3. {DEFAULT_OPTIONS}
+        #
+        # @api private
         module Configuration
+          # Returns the default covered components for signature verification.
+          # @return [Array<String>] the default components from {Linzer::Options::DEFAULT}
           def default_covered_components
             Linzer::Options::DEFAULT[:covered_components]
           end
           module_function :default_covered_components
 
+          # Default middleware configuration.
+          #
+          # @api private
           DEFAULT_OPTIONS = {
             signatures: {
               reject_older_than:  900,
@@ -62,6 +102,10 @@ module Rack
 
           private
 
+          # Loads and merges options from all sources.
+          #
+          # @param options [Hash] options passed to the middleware constructor
+          # @return [Hash] the merged configuration
           def load_options(options)
             options_from_file = load_options_from_config_file(options)
             {
@@ -78,6 +122,10 @@ module Rack
             }
           end
 
+          # Loads configuration from a YAML file.
+          #
+          # @param options [Hash] options containing +:config_path+
+          # @return [Hash] parsed configuration, or empty hash if unavailable
           def load_options_from_config_file(options)
             config_path = options[:config_path]
             YAML.safe_load_file(config_path, symbolize_names: true)
@@ -86,13 +134,29 @@ module Rack
           end
         end
 
+        # Resolves verification keys from the middleware configuration.
+        #
+        # Keys can be configured inline (with +:material+) or via file path
+        # (with +:path+). When a +keyid+ is present in the signature, the
+        # corresponding key is looked up in the +:keys+ hash. If not found,
+        # the +:default_key+ is used as fallback.
+        #
+        # @api private
         module Key
           private
 
+          # Returns the verification key for the current signature.
+          # @return [Linzer::Key] the resolved key
+          # @raise [Linzer::Error] if no key can be found
           def key
             build_key(params["keyid"])
           end
 
+          # Builds a key instance from configuration.
+          #
+          # @param keyid [String, nil] the key identifier from the signature
+          # @return [Linzer::Key] the resolved key
+          # @raise [Linzer::Error] if no matching key configuration is found
           def build_key(keyid)
             key_data = if keyid.nil? ||
                 (!options[:keys].key?(keyid.to_sym) && options[:default_key])
@@ -114,6 +178,14 @@ module Rack
             instantiate_key(keyid || :default, alg, key_data)
           end
 
+          # Instantiates the appropriate key class for the given algorithm.
+          #
+          # @param keyid [String, Symbol] the key identifier
+          # @param alg [String, Symbol] the algorithm identifier
+          #   (e.g. +"ed25519"+, +"rsa-pss-sha512"+)
+          # @param key_data [Hash] key configuration with +:material+
+          # @return [Linzer::Key] the instantiated key
+          # @raise [Linzer::Error] if the algorithm is unsupported
           def instantiate_key(keyid, alg, key_data)
             key_methods = {
               "rsa-pss-sha512"    => :new_rsa_pss_sha512_key,