linzer 0.7.9.beta2 → 0.7.9

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"
 end

data/lib/linzer.rb

@@ -4,7 +4,6 @@ require "starry"
 require "openssl"
 require "rack"
 require "uri"
-require "stringio"
 require "net/http"
 
 require_relative "linzer/version"

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,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: linzer
 version: !ruby/object:Gem::Version
-  version: 0.7.9.beta2
+  version: 0.7.9
 platform: ruby
 authors:
 - Miguel Landaeta
@@ -63,26 +63,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.2
-- !ruby/object:Gem::Dependency
-  name: stringio
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 3.1.2
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.1'
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 3.1.2
 - !ruby/object:Gem::Dependency
   name: logger
   requirement: !ruby/object:Gem::Requirement
@@ -182,10 +162,14 @@ files:
 - examples/sinatra/myapp.rb
 - flake.lock
 - flake.nix
+- lib/faraday/http_signature.rb
+- lib/faraday/http_signature/middleware.rb
 - lib/linzer.rb
 - lib/linzer/common.rb
 - lib/linzer/ecdsa.rb
 - lib/linzer/ed25519.rb
+- lib/linzer/faraday.rb
+- lib/linzer/faraday/utils.rb
 - lib/linzer/helper.rb
 - lib/linzer/hmac.rb
 - lib/linzer/http.rb
@@ -197,6 +181,8 @@ files:
 - lib/linzer/message.rb
 - lib/linzer/message/adapter.rb
 - lib/linzer/message/adapter/abstract.rb
+- lib/linzer/message/adapter/faraday/request.rb
+- lib/linzer/message/adapter/faraday/response.rb
 - lib/linzer/message/adapter/generic/request.rb
 - lib/linzer/message/adapter/generic/response.rb
 - lib/linzer/message/adapter/http_gem/common.rb