linzer 0.7.7.beta1 → 0.7.8

data/lib/linzer/key.rb

@@ -1,7 +1,39 @@
 # frozen_string_literal: true
 
 module Linzer
+  # Abstract base class for cryptographic keys used in HTTP message signatures.
+  #
+  # This class provides the common interface for all key types supported by Linzer.
+  # Do not instantiate this class directly; use one of the concrete subclasses
+  # or the key generation/loading helper methods.
+  #
+  # @abstract Subclass and override {#sign} and {#verify} to implement
+  #   a specific cryptographic algorithm.
+  #
+  # @example Using a concrete key class via helper methods
+  #   # Generate a new Ed25519 key pair
+  #   key = Linzer.generate_ed25519_key("my-key-id")
+  #
+  #   # Load an existing RSA-PSS key from PEM
+  #   key = Linzer.new_rsa_pss_sha512_key(File.read("private.pem"), "rsa-key")
+  #
+  # @see Ed25519::Key
+  # @see ECDSA::Key
+  # @see HMAC::Key
+  # @see RSA::Key
+  # @see RSAPSS::Key
+  # @see JWS::Key
   class Key
+    # Creates a new Key instance.
+    #
+    # @param material [OpenSSL::PKey::PKey, String] The key material.
+    #   For asymmetric keys, this is typically an OpenSSL key object.
+    #   For HMAC, this is the raw secret bytes.
+    # @param params [Hash] Additional key parameters
+    # @option params [String] :id The key identifier (keyid) for this key
+    # @option params [String] :digest The digest algorithm (e.g., "SHA256", "SHA512")
+    #
+    # @raise [Error] If key material is nil or invalid
     def initialize(material, params = {})
       @material = material
       @params   = Hash(params).clone.freeze
@@ -9,54 +41,95 @@ module Linzer
       freeze
     end
 
+    # @return [Object] The underlying key material
     attr_reader :material
 
+    # Returns the key identifier.
+    #
+    # The key ID is used in the `keyid` parameter of HTTP signatures to
+    # identify which key was used for signing.
+    #
+    # @return [String, nil] The key identifier, or nil if not set
     def key_id
       @params[:id]
     end
 
+    # Signs data using this key.
+    #
+    # @abstract Subclasses must override this method.
+    #
+    # @param args [Array] Implementation-specific arguments (typically data to sign)
+    # @return [String] The signature bytes
+    # @raise [Error] If called on the abstract base class
+    # @raise [SigningError] If the key cannot be used for signing
     def sign(*args)
       abstract_error = "Cannot sign data, \"#{self.class}\" is an abstract class."
       raise Error, abstract_error
     end
 
+    # Verifies a signature against data using this key.
+    #
+    # @abstract Subclasses must override this method.
+    #
+    # @param args [Array] Implementation-specific arguments (typically signature and data)
+    # @return [Boolean] true if the signature is valid, false otherwise
+    # @raise [Error] If called on the abstract base class
+    # @raise [VerifyError] If the key cannot be used for verification
     def verify(*args)
       abstract_error = "Cannot verify signature, \"#{self.class}\" is an abstract class."
       raise Error, abstract_error
     end
 
+    # Checks if this key can be used for signature verification.
+    #
+    # @return [Boolean] true if the key contains public key material
     def public?
       material.public?
     end
 
+    # Checks if this key can be used for signing.
+    #
+    # @return [Boolean] true if the key contains private key material
     def private?
       material.private?
     end
 
     private
 
+    # Validates that the key has material.
+    # @raise [Error] If key material is nil
     def validate
       !material.nil? or raise Error.new "Invalid key. No key material provided."
     end
 
+    # Validates that a digest algorithm is configured.
+    # @raise [Error] If no digest algorithm is set
     def validate_digest
       no_digest = !@params.key?(:digest) || @params[:digest].nil? || String(@params[:digest]).empty?
       no_digest_error = "Invalid key definition, no digest algorithm was selected."
       raise Error, no_digest_error if no_digest
     end
 
+    # Validates that this key can be used for signing.
+    # @raise [SigningError] If the key does not contain private material
     def validate_signing_key
       raise SigningError, "Private key is needed!" unless private?
     end
 
+    # Validates that this key can be used for verification.
+    # @raise [VerifyError] If the key does not contain public material
     def validate_verify_key
       raise VerifyError, "Public key is needed!" unless public?
     end
 
+    # Checks if the key material has a PEM-encoded public key.
+    # @return [Boolean]
     def has_pem_public?
       material.public_to_pem.match?(/^-----BEGIN PUBLIC KEY-----/)
     end
 
+    # Checks if the key material has a PEM-encoded private key.
+    # @return [Boolean]
     def has_pem_private?
       material.private_to_pem.match?(/^-----BEGIN PRIVATE KEY-----/)
     rescue

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

@@ -3,61 +3,122 @@
 module Linzer
   class Message
     module Adapter
+      # Abstract base class for HTTP message adapters.
+      #
+      # Adapters provide a unified interface for accessing HTTP message
+      # components regardless of the underlying HTTP library. Each adapter
+      # implements field retrieval, header access, and signature attachment
+      # for a specific HTTP message type.
+      #
+      # @abstract Subclass and implement {#header}, {#attach!}, {#derived},
+      #   and {#field} to create a new adapter.
+      #
+      # @see Rack::Request Rack request adapter
+      # @see Rack::Response Rack response adapter
+      # @see NetHTTP::Request Net::HTTP request adapter
+      # @see NetHTTP::Response Net::HTTP response adapter
       class Abstract
+        # @raise [Error] This class cannot be instantiated directly
         def initialize(operation, **options)
           raise Linzer::Error, "Cannot instantiate an abstract class!"
         end
 
+        # Checks if this adapter wraps an HTTP request.
+        # @return [Boolean] true if the wrapped message is a request
         def request?
           self.class.to_s.include?("Request")
         end
 
+        # Checks if this adapter wraps an HTTP response.
+        # @return [Boolean] true if the wrapped message is a response
         def response?
           self.class.to_s.include?("Response")
         end
 
+        # Checks if this response has an attached request.
+        #
+        # Attached requests enable the `;req` parameter for accessing
+        # request fields from a response signature.
+        #
+        # @return [Boolean] true if an attached request is present
         def attached_request?
           response? && !!@attached_request
         end
 
+        # Checks if a component exists in the message.
+        #
+        # @param f [String] The component identifier
+        # @return [Boolean] true if the component can be retrieved
         def field?(f)
           !!self[f]
         end
 
+        # Retrieves a component value from the message.
+        #
+        # Handles both regular header fields and derived components,
+        # including parameter processing (`;sf`, `;bs`, `;req`, `;key`).
+        #
+        # @param field [String, FieldId] The component identifier
+        # @return [String, Integer, nil] The component value, or nil if not found
+        #
+        # @example Header field
+        #   adapter["content-type"]  # => "application/json"
+        #
+        # @example Derived component
+        #   adapter["@method"]  # => "POST"
+        #
+        # @example With structured field parameter
+        #   adapter['"example-dict";key="a"']  # => "1"
         def [](field)
           field_id = field.is_a?(FieldId) ? field : parse_field_name(field)
           return nil if field_id.nil? || field_id.item.nil?
           retrieve(field_id.item, field_id.derived? ? :derived : :field)
         end
 
+        # Retrieves a raw header value by name.
+        #
+        # @abstract Subclasses must implement this method.
+        # @param name [String] The header name
+        # @return [String, nil] The header value
         def header(name)
           raise Linzer::Error, "Sub-classes are required to implement this method!"
         end
 
+        # Attaches a signature to the underlying HTTP message.
+        #
+        # @abstract Subclasses must implement this method.
+        # @param signature [Signature] The signature to attach
+        # @return [Object] The underlying HTTP message
         def attach!(signature)
           raise Linzer::Error, "Sub-classes are required to implement this method!"
         end
 
         private
 
+        # Parses a field name string into a FieldId.
+        # @return [FieldId, nil] The parsed identifier, or nil if invalid
         def parse_field_name(field_name)
           field_id  = FieldId.new(field_name: field_name)
           component = field_id.item
 
           return nil if component.nil?
 
-          # 2.2.9
+          # RFC 9421 Section 2.2.9: @status is only valid for responses
           invalid = "@status component identifier is invalid in a request message"
           raise Error, invalid if request? && component.value == "@status"
 
           field_id
         end
 
+        # Validates that an attached message is a request.
+        # @raise [Error] If the message is not a request
         def validate_attached_request(message)
           msg = "The attached message is not a valid HTTP request!"
           raise Linzer::Error, msg unless message.request?
         end
 
+        # Validates component identifier parameters.
+        # @return [Object, nil] The validated name, or nil if invalid
         def validate_parameters(name, method)
           has_unknown = name.parameters.any? { |p, _| !KNOWN_PARAMETERS.include?(p) }
           return nil if has_unknown
@@ -68,29 +129,26 @@ module Linzer
           has_bs   = name.parameters["bs"]
           value    = name.value
 
-          # Section 2.2.8 of RFC 9421
+          # Section 2.2.8 of RFC 9421: name param only for @query-param
           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
+          # RFC 9421 Section 2.1: bs incompatible with sf/key
           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?)
+          # req param only makes sense on responses
           return nil if has_req && !response?
 
           name
         end
 
+        # Known component identifier parameters from RFC 9421.
         KNOWN_PARAMETERS = %w[sf key bs req tr name]
         private_constant :KNOWN_PARAMETERS
 
+        # Retrieves a component value with parameter processing.
         def retrieve(name, method)
           if !name.parameters.empty?
             valid_params = validate_parameters(name, method)
@@ -117,6 +175,8 @@ module Linzer
           end
         end
 
+        # Processes a structured field value with optional key extraction.
+        # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-2.1.1
         def sf(value, key = nil)
           dict = Starry.parse_dictionary(value)
 
@@ -128,14 +188,19 @@ module Linzer
           end
         end
 
+        # Binary-wraps a field value.
+        # @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.
         def tr(trailer)
-          @operation.body.trailers[trailer.value.to_s]
+          raise Error, "Sub-classes are required to implement this method!"
         end
 
+        # Retrieves a field from the attached request.
         def req(field, method)
           attached_request? ? @attached_request[String(field)] : nil
         end

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

@@ -5,17 +5,44 @@ require "cgi"
 module Linzer
   class Message
     module Adapter
+      # Generic adapters for HTTP messages.
+      #
+      # These adapters provide a base implementation that can be extended
+      # for HTTP libraries not directly supported by Linzer.
       module Generic
+        # Generic HTTP request adapter.
+        #
+        # Provides a base implementation for request message access.
+        # Assumes the operation responds to `[]` for header access and
+        # has a `uri` attribute.
+        #
+        # @example Creating a custom adapter
+        #   class MyRequestAdapter < Linzer::Message::Adapter::Generic::Request
+        #     private
+        #     def derived(name)
+        #       return @operation.http_method if name.value == "@method"
+        #       super
+        #     end
+        #   end
         class Request < Abstract
+          # Creates a new request adapter.
+          # @param operation [Object] The HTTP request object
+          # @param options [Hash] Additional options (unused in base class)
           def initialize(operation, **options)
             @operation = operation
             freeze
           end
 
+          # Retrieves a header value by name.
+          # @param name [String] The header name
+          # @return [String, nil] The header value
           def header(name)
             @operation[name]
           end
 
+          # Attaches a signature to the request.
+          # @param signature [Signature] The signature to attach
+          # @return [Object] The underlying request object
           def attach!(signature)
             signature.to_h.each { |h, v| @operation[h] = v }
             @operation

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

@@ -4,7 +4,18 @@ module Linzer
   class Message
     module Adapter
       module Generic
+        # Generic HTTP response adapter.
+        #
+        # Provides a base implementation for response message access.
+        # Assumes the operation responds to `[]` for header access.
+        #
+        # @abstract Subclass must implement {#derived} method.
         class Response < Abstract
+          # Creates a new response adapter.
+          # @param operation [Object] The HTTP response object
+          # @param options [Hash] Additional options
+          # @option options [Object] :attached_request An associated request
+          #   for `;req` parameter support
           def initialize(operation, **options)
             @operation = operation
             attached_request = options[:attached_request]
@@ -13,10 +24,16 @@ module Linzer
             freeze
           end
 
+          # Retrieves a header value by name.
+          # @param name [String] The header name
+          # @return [String, nil] The header value
           def header(name)
             @operation[name]
           end
 
+          # Attaches a signature to the response.
+          # @param signature [Signature] The signature to attach
+          # @return [Object] The underlying response object
           def attach!(signature)
             signature.to_h.each { |h, v| @operation[h] = v }
             @operation

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

@@ -3,7 +3,18 @@
 module Linzer
   class Message
     module Adapter
+      # http.rb gem message adapters.
+      #
+      # Provides adapters for {HTTP::Request} and {HTTP::Response} objects
+      # from the http.rb gem.
+      #
+      # @note These adapters are loaded on-demand when using the
+      #   {Linzer::HTTP::SignatureFeature}.
       module HTTPGem
+        # Adapter for {HTTP::Request} objects from http.rb gem.
+        #
+        # Extends the generic request adapter with http.rb-specific
+        # method name retrieval.
         class Request < Generic::Request
           private
 

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

@@ -1,14 +1,17 @@
 # frozen_string_literal: true
 
-# HTTP message adapter for HTTP::Response class from http ruby gem.
-# https://github.com/httprb/http
-#
-# It's not loaded automatically to avoid making http gem a dependency.
-#
 module Linzer
   class Message
     module Adapter
       module HTTPGem
+        # Adapter for {HTTP::Response} objects from http.rb gem.
+        #
+        # Extends the generic response adapter with http.rb-specific
+        # status code retrieval.
+        #
+        # @note Not loaded automatically to avoid making http gem a dependency.
+        #
+        # @see https://github.com/httprb/http http.rb gem
         class Response < Generic::Response
           private
 

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

@@ -3,7 +3,14 @@
 module Linzer
   class Message
     module Adapter
+      # Net::HTTP message adapters.
+      #
+      # Provides adapters for {Net::HTTPRequest} and {Net::HTTPResponse} objects.
       module NetHTTP
+        # Adapter for {Net::HTTPRequest} objects.
+        #
+        # Extends the generic request adapter with Net::HTTP-specific
+        # method name retrieval.
         class Request < Generic::Request
           private
 

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

@@ -4,6 +4,10 @@ module Linzer
   class Message
     module Adapter
       module NetHTTP
+        # Adapter for {Net::HTTPResponse} objects.
+        #
+        # Extends the generic response adapter with Net::HTTP-specific
+        # status code retrieval.
         class Response < Generic::Response
           private
 

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

@@ -3,7 +3,12 @@
 module Linzer
   class Message
     module Adapter
+      # Rack HTTP message adapters.
+      #
+      # Provides adapters for {::Rack::Request} and {::Rack::Response} objects.
       module Rack
+        # Shared functionality for Rack request and response adapters.
+        # @api private
         module Common
           DERIVED_COMPONENT = {
             "@method"         => :request_method,
@@ -61,14 +66,17 @@ module Linzer
 
           def field(name)
             has_tr = name.parameters["tr"]
-            if has_tr
-              value = tr(name)
+            return nil if has_tr
+
+            item_value  = String(name.value)
+            field_value = if request?
+              rack_header_name = rack_header_name(item_value)
+              @operation.env[rack_header_name]
             else
-              rack_header_name = rack_header_name(name.value.to_s)
-              value = @operation.env[rack_header_name] if request?
-              value = @operation.get_header(name.value.to_s) if response?
+              @operation.get_header(item_value)
             end
-            value.dup&.strip
+
+            field_value.dup&.strip
           end
 
           def derive(operation, method)

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

@@ -4,19 +4,32 @@ module Linzer
   class Message
     module Adapter
       module Rack
+        # Adapter for {::Rack::Request} objects.
+        #
+        # Handles the Rack-specific header naming conventions (HTTP_* prefix,
+        # uppercase, underscores).
         class Request < Abstract
           include Common
 
+          # Creates a new Rack request adapter.
+          # @param operation [::Rack::Request] The Rack request
+          # @param options [Hash] Additional options (unused)
           def initialize(operation, **options)
             @operation = operation
             validate
             freeze
           end
 
+          # Retrieves a header value by name.
+          # @param name [String] The header name (e.g., "content-type")
+          # @return [String, nil] The header value
           def header(name)
             @operation.get_header(rack_header_name(name))
           end
 
+          # Attaches a signature to the request.
+          # @param signature [Signature] The signature to attach
+          # @return [::Rack::Request] The request with signature headers
           def attach!(signature)
             signature.to_h.each do |h, v|
               @operation.set_header(rack_header_name(h), v)

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

@@ -4,9 +4,14 @@ module Linzer
   class Message
     module Adapter
       module Rack
+        # Adapter for {::Rack::Response} objects.
         class Response < Abstract
           include Common
 
+          # Creates a new Rack response adapter.
+          # @param operation [::Rack::Response] The Rack response
+          # @param options [Hash] Additional options
+          # @option options [Object] :attached_request Request for `;req` support
           def initialize(operation, **options)
             @operation = operation
             validate
@@ -16,10 +21,16 @@ module Linzer
             freeze
           end
 
+          # Retrieves a header value by name.
+          # @param name [String] The header name
+          # @return [String, nil] The header value
           def header(name)
             @operation.get_header(name)
           end
 
+          # Attaches a signature to the response.
+          # @param signature [Signature] The signature to attach
+          # @return [::Rack::Response] The response with signature headers
           def attach!(signature)
             signature.to_h.each do |h, v|
               @operation.set_header(h, v)

data/lib/linzer/message/adapter.rb

@@ -8,3 +8,20 @@ require_relative "adapter/rack/request"
 require_relative "adapter/rack/response"
 require_relative "adapter/net_http/request"
 require_relative "adapter/net_http/response"
+
+module Linzer
+  class Message
+    # Namespace for HTTP message adapters.
+    #
+    # Adapters provide a unified interface for accessing HTTP message
+    # components across different HTTP libraries. Each supported library
+    # has its own adapter implementation.
+    #
+    # @see Abstract Base adapter class
+    # @see Rack Rack request/response adapters
+    # @see NetHTTP Net::HTTP request/response adapters
+    # @see Generic Generic adapters for extension
+    module Adapter
+    end
+  end
+end

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

@@ -4,9 +4,23 @@ module Linzer
   class Message
     class Field
       class Identifier
+        # Parses component identifier strings into structured items.
+        #
+        # Handles various formats:
+        # - Simple names: `"content-type"`
+        # - Derived components: `"@method"`
+        # - With parameters: `"content-type";bs`, `"example-dict";key="a"`
+        # - Already serialized: `'"content-type"'`
+        #
+        # @api private
         module Parser
           extend self
 
+          # Parses a field name into a structured item.
+          #
+          # @param field_name [String] The component identifier string
+          # @return [Starry::Item] The parsed structured field item
+          # @raise [Error] If the field name cannot be parsed
           def parse(field_name)
             case
             when field_name.match?(/";/), field_name.start_with?('"')