linzer 0.7.7 → 0.7.8

data/lib/linzer/message/field.rb

@@ -2,27 +2,48 @@
 
 module Linzer
   class Message
+    # Handles HTTP message field identification and serialization.
+    #
+    # Fields represent HTTP header fields and derived components that can
+    # be included in signatures. This class handles parsing and serialization
+    # of component identifiers according to RFC 9421.
+    #
+    # @api private
     class Field
+      # Methods mixed into the Identifier class for field name handling.
+      # @api private
       module IdentifierMethods
+        # Initializes the identifier by parsing the field name.
+        # @param field_name [String] The component identifier string
         def initialize(field_name:)
           @item = Identifier::Parser.parse(field_name) rescue nil
           super
         end
 
+        # @return [Starry::Item, nil] The parsed structured field item
         attr_reader :item
 
+        # Checks if this is a derived component (starts with @).
+        # @return [Boolean] true if derived (e.g., @method, @path)
         def derived?
           item&.value&.start_with?("@")
         end
 
+        # Serializes the component identifier.
+        # @return [String] The serialized identifier (e.g., '"@method"')
+        # @raise [Error] If the component identifier is invalid
         def serialize
           raise Error, "Invalid component identifier: '#{field_name}'!" unless item
           Starry.serialize(@item)
         end
       end
 
-      # Excluded from coverage as obviously both branches cannot be covered
-      # on a single test run.
+      # Component identifier for HTTP message fields.
+      #
+      # Uses Data.define on Ruby 3.2+ for immutability, falls back to Struct
+      # on older versions.
+      #
+      # @api private
       # :nocov:
       if Gem::Version.new(RUBY_VERSION) < Gem::Version.new("3.2.0")
         class Identifier < Struct.new(:field_name, keyword_init: true); end
@@ -35,14 +56,23 @@ module Linzer
 
       class Identifier
         class << self
+          # Serializes a single component identifier.
+          # @param component [String] The component name
+          # @return [String] The serialized identifier
           def serialize(component)
             new(field_name: component).serialize
           end
 
+          # Serializes an array of component identifiers.
+          # @param components [Array<String>] Component names
+          # @return [Array<String>] Serialized identifiers
           def serialize_components(components)
             components.map(&method(:serialize))
           end
 
+          # Deserializes component identifiers back to names.
+          # @param components [Array<String>] Serialized identifiers
+          # @return [Array<String>] Component names
           def deserialize_components(components)
             components.map do |c|
               item = Starry.parse_item(c)

data/lib/linzer/message/wrapper.rb

@@ -2,7 +2,15 @@
 
 module Linzer
   class Message
+    # Handles wrapping HTTP messages with the appropriate adapter.
+    #
+    # This module maintains a registry of adapter classes for different
+    # HTTP message types (Rack, Net::HTTP, etc.) and selects the correct
+    # one when wrapping a message.
+    #
+    # @api private
     module Wrapper
+      # Default adapter mappings for built-in HTTP library support.
       @adapters = {
         Rack::Request     => Linzer::Message::Adapter::Rack::Request,
         Rack::Response    => Linzer::Message::Adapter::Rack::Response,
@@ -11,6 +19,12 @@ module Linzer
       }
 
       class << self
+        # Wraps an HTTP message with the appropriate adapter.
+        #
+        # @param operation [Object] The HTTP request or response object
+        # @param options [Hash] Additional options (e.g., :attached_request)
+        # @return [Adapter::Abstract] The wrapped message
+        # @raise [Error] If no suitable adapter is found
         def wrap(operation, **options)
           adapter_class = adapters[operation.class]
 
@@ -22,6 +36,10 @@ module Linzer
           (adapter_class || ancestor).new(operation, **options)
         end
 
+        # Registers a custom adapter for an HTTP message class.
+        #
+        # @param operation_class [Class] The HTTP message class
+        # @param adapter_class [Class] The adapter class to use
         def register_adapter(operation_class, adapter_class)
           adapters[operation_class] = adapter_class
         end
@@ -30,6 +48,8 @@ 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.
         def find_ancestor(operation)
           adapters
             .select { |klz, adpt| operation.is_a? klz }

data/lib/linzer/message.rb

@@ -3,24 +3,134 @@
 require "forwardable"
 
 module Linzer
+  # Wraps an HTTP request or response for signing and verification.
+  #
+  # Message provides a unified interface for accessing HTTP message components
+  # regardless of the underlying HTTP library (Rack, Net::HTTP, http.rb, etc.).
+  # It handles the extraction of both regular header fields and derived
+  # components (like `@method`, `@path`, `@authority`).
+  #
+  # @example Wrapping a Rack request
+  #   request = Rack::Request.new(env)
+  #   message = Linzer::Message.new(request)
+  #   message.request?  # => true
+  #   message["@method"] # => "GET"
+  #
+  # @example Wrapping a Net::HTTP request
+  #   request = Net::HTTP::Post.new(uri)
+  #   request["content-type"] = "application/json"
+  #   message = Linzer::Message.new(request)
+  #   message["content-type"]  # => "application/json"
+  #
+  # @example Wrapping a response with an attached request
+  #   response = Net::HTTPOK.new("1.1", "200", "OK")
+  #   message = Linzer::Message.new(response, attached_request: request)
+  #   message["@status"]  # => 200
+  #   message['"content-type";req']  # => value from the attached request
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-2 RFC 9421 Section 2
   class Message
     extend Forwardable
 
+    # Creates a new Message wrapper.
+    #
+    # @param operation [Rack::Request, Rack::Response, Net::HTTPRequest,
+    #   Net::HTTPResponse, HTTP::Request, HTTP::Response] The HTTP message to wrap.
+    #   Linzer automatically selects the appropriate adapter based on the class.
+    # @param attached_request [Object, nil] For response messages, an optional
+    #   request that can be referenced using the `;req` parameter in component
+    #   identifiers. This enables signing responses that cover request fields.
+    #
+    # @raise [Error] If the operation class is not supported and no adapter
+    #   has been registered for it.
+    #
+    # @example Basic usage
+    #   message = Linzer::Message.new(request)
+    #
+    # @example Response with attached request (for `;req` parameter support)
+    #   message = Linzer::Message.new(response, attached_request: original_request)
     def initialize(operation, attached_request: nil)
       @adapter = Wrapper.wrap(operation, attached_request: attached_request)
       freeze
     end
 
-    # common predicates
+    # @!method request?
+    #   Checks if this message wraps an HTTP request.
+    #   @return [Boolean] true if the underlying message is a request
+
+    # @!method response?
+    #   Checks if this message wraps an HTTP response.
+    #   @return [Boolean] true if the underlying message is a response
+
+    # @!method attached_request?
+    #   Checks if this response message has an attached request.
+    #   @return [Boolean] true if an attached request is present
     def_delegators :@adapter, :request?, :response?, :attached_request?
 
-    # fields look up
+    # @!method header(name)
+    #   Retrieves a header value by name.
+    #   @param name [String] The header name (case-insensitive)
+    #   @return [String, nil] The header value, or nil if not present
+
+    # @!method field?(component)
+    #   Checks if a component exists in the message.
+    #   @param component [String] The component identifier
+    #   @return [Boolean] true if the component can be retrieved
+
+    # @!method [](component)
+    #   Retrieves a component value from the message.
+    #
+    #   Supports both regular header fields and derived components:
+    #   - Header fields: `"content-type"`, `"date"`, `"x-custom-header"`
+    #   - Derived components: `"@method"`, `"@path"`, `"@authority"`, `"@status"`
+    #   - With parameters: `"content-type";bs`, `"example-dict";key="a"`, `"date";req`
+    #
+    #   @param component [String] The component identifier, optionally with parameters
+    #   @return [String, Integer, nil] The component value, or nil if not found
+    #
+    #   @example Accessing headers
+    #     message["content-type"]  # => "application/json"
+    #
+    #   @example Accessing derived components
+    #     message["@method"]  # => "POST"
+    #     message["@path"]    # => "/api/resource"
+    #
+    #   @example With parameters
+    #     message['"content-type";bs']  # => base64-encoded value
     def_delegators :@adapter, :header, :field?, :[]
 
-    # to attach a signature to the underlying HTTP message
+    # @!method attach!(signature)
+    #   Attaches a signature to the underlying HTTP message.
+    #
+    #   Modifies the original HTTP message by adding the `signature` and
+    #   `signature-input` headers from the signature.
+    #
+    #   @param signature [Linzer::Signature] The signature to attach
+    #   @return [Object] The underlying HTTP message object
+    #
+    #   @example
+    #     signature = Linzer.sign(key, message, components)
+    #     message.attach!(signature)
     def_delegators :@adapter, :attach!
 
     class << self
+      # Registers a custom adapter for an HTTP message class.
+      #
+      # Use this to add support for HTTP libraries not built into Linzer.
+      # The adapter class must inherit from {Adapter::Abstract} and implement
+      # the required interface.
+      #
+      # @param operation_class [Class] The HTTP message class to register
+      # @param adapter_class [Class] The adapter class to use for wrapping
+      #
+      # @example Registering a custom adapter
+      #   class MyHttpRequest; end
+      #   class MyAdapter < Linzer::Message::Adapter::Abstract
+      #     # ... implementation
+      #   end
+      #   Linzer::Message.register_adapter(MyHttpRequest, MyAdapter)
+      #
+      # @see Adapter::Abstract
       def register_adapter(operation_class, adapter_class)
         Wrapper.register_adapter(operation_class, adapter_class)
       end

data/lib/linzer/options.rb

@@ -1,7 +1,20 @@
 # frozen_string_literal: true
 
 module Linzer
+  # Default configuration options for HTTP message signatures.
+  #
+  # These defaults provide a reasonable starting point for most applications.
+  # They can be overridden when signing or in middleware configuration.
   module Options
+    # Default configuration values.
+    #
+    # @return [Hash] Frozen hash of default options
+    #
+    # @option DEFAULT [Array<String>] :covered_components Default components
+    #   to include in signatures: `@method`, `@request-target`, `@authority`,
+    #   and `date`. These provide good baseline security for most use cases.
+    #
+    # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-7.2.1 RFC 9421 Section 7.2.1
     DEFAULT = {
       covered_components: %w[@method @request-target @authority date]
     }.freeze

data/lib/linzer/rsa.rb

@@ -1,18 +1,52 @@
 # frozen_string_literal: true
 
 module Linzer
+  # RSA PKCS#1 v1.5 signature algorithm support.
+  #
+  # This implements the traditional RSA signature scheme using PKCS#1 v1.5
+  # padding. For new applications, consider using RSA-PSS ({RSAPSS}) instead,
+  # which provides better security properties.
+  #
+  # @note RSA-PSS is recommended over PKCS#1 v1.5 for new applications.
+  #
+  # @see RSAPSS RSA-PSS (recommended)
+  # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-3.3.2 RFC 9421 Section 3.3.2
   module RSA
+    # RSA PKCS#1 v1.5 signing key implementation.
+    #
+    # Uses the `rsa-v1_5-sha256` algorithm identifier.
+    #
+    # @example Generating a new key
+    #   key = Linzer.generate_rsa_v1_5_sha256_key(2048, "my-rsa-key")
+    #
+    # @example Loading from PEM
+    #   key = Linzer.new_rsa_v1_5_sha256_key(File.read("rsa.pem"), "key-1")
+    #
+    # @see Linzer::Key::Helper#generate_rsa_v1_5_sha256_key
+    # @see Linzer::Key::Helper#new_rsa_v1_5_sha256_key
     class Key < Linzer::Key
+      # @api private
       def validate
         super
         validate_digest
       end
 
+      # Signs data using RSA PKCS#1 v1.5.
+      #
+      # @param data [String] The data to sign
+      # @return [String] The RSA signature
+      # @raise [SigningError] If this key does not contain private key material
       def sign(data)
         validate_signing_key
         material.sign(@params[:digest], data)
       end
 
+      # Verifies an RSA PKCS#1 v1.5 signature.
+      #
+      # @param signature [String] The signature bytes to verify
+      # @param data [String] The data that was signed
+      # @return [Boolean] true if the signature is valid, false otherwise
+      # @raise [VerifyError] If this key does not contain public key material
       def verify(signature, data)
         validate_verify_key
         material.verify(@params[:digest], signature, data)

data/lib/linzer/rsa_pss.rb

@@ -1,20 +1,60 @@
 # frozen_string_literal: true
 
 module Linzer
+  # RSA-PSS (RSASSA-PSS) signature algorithm support.
+  #
+  # RSA-PSS is the recommended RSA signature scheme, providing better
+  # security properties than the older PKCS#1 v1.5 scheme. It uses
+  # probabilistic padding which makes signatures non-deterministic.
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-3.3.1 RFC 9421 Section 3.3.1
+  # @see https://www.rfc-editor.org/rfc/rfc8017.html#section-8.1 RFC 8017 RSASSA-PSS
   module RSAPSS
+    # Default salt length for PSS padding (64 bytes).
+    # @return [Integer]
     SALT_LENGTH = 64
 
+    # RSA-PSS signing key implementation.
+    #
+    # Uses the `rsa-pss-sha512` algorithm identifier with a 64-byte salt.
+    #
+    # @note RSA-PSS signatures are non-deterministic due to random salt.
+    #   The same data signed twice will produce different signatures,
+    #   but both will verify successfully.
+    #
+    # @example Generating a new key
+    #   key = Linzer.generate_rsa_pss_sha512_key(2048, "my-key")
+    #
+    # @example Loading from PEM
+    #   key = Linzer.new_rsa_pss_sha512_key(File.read("rsa_pss.pem"), "key-1")
+    #
+    # @see Linzer::Key::Helper#generate_rsa_pss_sha512_key
+    # @see Linzer::Key::Helper#new_rsa_pss_sha512_key
     class Key < Linzer::Key
+      # @api private
       def validate
         super
         validate_digest
       end
 
+      # Signs data using RSA-PSS.
+      #
+      # @param data [String] The data to sign
+      # @return [String] The RSA-PSS signature
+      # @raise [SigningError] If this key does not contain private key material
+      #
+      # @note The signature is non-deterministic due to random PSS salt.
       def sign(data)
         validate_signing_key
         material.sign(@params[:digest], data, signature_options)
       end
 
+      # Verifies an RSA-PSS signature.
+      #
+      # @param signature [String] The signature bytes to verify
+      # @param data [String] The data that was signed
+      # @return [Boolean] true if the signature is valid, false otherwise
+      # @raise [VerifyError] If this key does not contain public key material
       def verify(signature, data)
         validate_verify_key
         material.verify(
@@ -25,16 +65,20 @@ module Linzer
         )
       end
 
+      # @return [Boolean] true if this key contains public key material
       def public?
         has_pem_public?
       end
 
+      # @return [Boolean] true if this key contains private key material
       def private?
         has_pem_private?
       end
 
       private
 
+      # Returns OpenSSL options for PSS signature operations.
+      # @return [Hash] OpenSSL signature options
       def signature_options
         {
           rsa_padding_mode: "pss",

data/lib/linzer/signature.rb

@@ -1,7 +1,32 @@
 # frozen_string_literal: true
 
 module Linzer
+  # Represents an HTTP message signature as defined in RFC 9421.
+  #
+  # A Signature encapsulates:
+  # - The raw signature bytes
+  # - The covered components (fields included in the signature)
+  # - The signature parameters (created, keyid, etc.)
+  # - The signature label (for identifying multiple signatures)
+  #
+  # Signatures are immutable once created. Use {.build} to create instances
+  # from HTTP headers, or receive them from {Signer.sign}.
+  #
+  # @example Building a signature from HTTP headers
+  #   headers = {
+  #     "signature-input" => 'sig1=("@method" "@path");created=1618884473',
+  #     "signature" => "sig1=:base64encodedvalue...:"
+  #   }
+  #   signature = Linzer::Signature.build(headers)
+  #
+  # @example Attaching a signature to a request
+  #   signature = Linzer.sign(key, message, components)
+  #   signature.to_h.each { |name, value| request[name] = value }
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-4 RFC 9421 Section 4
   class Signature
+    # @api private
+    # Use {.build} to create Signature instances.
     def initialize(metadata, value, label, parameters = {})
       @metadata   = metadata.clone.freeze
       @value      = value.clone.freeze
@@ -10,14 +35,50 @@ module Linzer
       freeze
     end
 
-    attr_reader  :metadata, :value, :parameters, :label
+    # @!attribute [r] metadata
+    #   @return [Array<String>] The serialized component identifiers
+    #   @see #serialized_components
+    attr_reader :metadata
+
+    # @!attribute [r] value
+    #   @return [String] The raw signature bytes (binary string)
+    attr_reader :value
+
+    # @!attribute [r] parameters
+    #   @return [Hash] The signature parameters (created, keyid, nonce, etc.)
+    #   @note Keys are strings, not symbols
+    attr_reader :parameters
+
+    # @!attribute [r] label
+    #   @return [String] The signature label (e.g., "sig1")
+    attr_reader :label
+
+    # @!method serialized_components
+    #   Returns the serialized component identifiers.
+    #   @return [Array<String>] Component identifiers in serialized form
+    #     (e.g., `['"@method"', '"content-type"']`)
     alias_method :serialized_components, :metadata
+
+    # @!method bytes
+    #   Returns the raw signature bytes.
+    #   @return [String] The signature value as binary string
     alias_method :bytes, :value
 
+    # Returns the deserialized component identifiers.
+    #
+    # Unlike {#serialized_components}, this returns the components in a more
+    # human-readable form.
+    #
+    # @return [Array<String>] Component identifiers (e.g., `["@method", "content-type"]`)
     def components
       FieldId.deserialize_components(serialized_components)
     end
 
+    # Returns the signature creation timestamp.
+    #
+    # @return [Integer, nil] Unix timestamp when the signature was created,
+    #   or nil if the `created` parameter is not present
+    # @raise [Error] If the `created` parameter exists but is not an integer
     def created
       Integer(parameters["created"])
     rescue
@@ -25,11 +86,31 @@ module Linzer
       raise Error.new "Signature has a non-integer `created` parameter"
     end
 
+    # Checks if the signature is older than a given number of seconds.
+    #
+    # This is useful for implementing replay attack protection by rejecting
+    # signatures that are too old.
+    #
+    # @param seconds [Integer] The maximum age in seconds
+    # @return [Boolean] true if the signature is older than the specified seconds
+    # @raise [Error] If the signature is missing the `created` parameter
+    #
+    # @example Check if signature is older than 5 minutes
+    #   signature.older_than?(300)  # => true or false
     def older_than?(seconds)
       raise Error.new "Signature is missing the `created` parameter" if created.nil?
       (Time.now.to_i - created) > seconds
     end
 
+    # Converts the signature to HTTP header format.
+    #
+    # Returns a hash suitable for setting as HTTP headers on a request or
+    # response. The hash contains `signature` and `signature-input` keys.
+    #
+    # @return [Hash{String => String}] Hash with "signature" and "signature-input" keys
+    #
+    # @example Attaching to a Net::HTTP request
+    #   signature.to_h.each { |name, value| request[name] = value }
     def to_h
       {
         "signature"       => Starry.serialize({label => value}),
@@ -45,6 +126,35 @@ module Linzer
     class << self
       private :new
 
+      # Builds a Signature from HTTP headers.
+      #
+      # Parses the `signature` and `signature-input` headers according to
+      # RFC 9421 and RFC 8941 (Structured Field Values).
+      #
+      # @param headers [Hash{String => String}] HTTP headers containing
+      #   `signature` and `signature-input` fields. Keys are case-insensitive.
+      # @param options [Hash] Build options
+      # @option options [String] :label The signature label to extract when
+      #   multiple signatures are present. If not specified and multiple
+      #   signatures exist, an error is raised.
+      #
+      # @return [Signature] The parsed signature
+      #
+      # @raise [Error] If headers are nil or empty
+      # @raise [Error] If required signature headers are missing
+      # @raise [Error] If multiple signatures exist and no label is specified
+      # @raise [Error] If the specified label is not found
+      # @raise [Error] If the headers cannot be parsed as structured fields
+      #
+      # @example Building from request headers
+      #   headers = {
+      #     "signature-input" => 'sig1=("@method");created=1618884473',
+      #     "signature" => "sig1=:HIbjHC5rS0BYaa9v4QfD4193TORw7u9..=:"
+      #   }
+      #   signature = Linzer::Signature.build(headers)
+      #
+      # @example Selecting a specific signature by label
+      #   signature = Linzer::Signature.build(headers, label: "sig2")
       def build(headers, options = {})
         basic_validate headers
         headers.transform_keys!(&:downcase)
@@ -99,6 +209,8 @@ module Linzer
         raise Error.new "Cannot parse \"#{field_name}\" field. Bailing out!"
       end
 
+      # Parses a structured field value as a dictionary.
+      # @see https://datatracker.ietf.org/doc/html/rfc8941 RFC 8941
       def parse_structured_field(hsh, field_name)
         # Serialized Structured Field values for HTTP are ASCII strings.
         # See: RFC 8941 (https://datatracker.ietf.org/doc/html/rfc8941)

data/lib/linzer/signer.rb

@@ -1,12 +1,72 @@
 # frozen_string_literal: true
 
 module Linzer
+  # Handles HTTP message signing according to RFC 9421.
+  #
+  # This module provides the core signing functionality. It creates signatures
+  # by computing a signature base from the message components and signing it
+  # with the provided key.
+  #
+  # @example Direct usage (prefer Linzer.sign for convenience)
+  #   message = Linzer::Message.new(request)
+  #   components = %w[@method @path content-type]
+  #   signature = Linzer::Signer.sign(key, message, components)
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-3.1 RFC 9421 Section 3.1
   module Signer
+    # Default label used for signatures when none is specified.
+    # @return [String]
     DEFAULT_LABEL = "sig1"
 
     class << self
       include Common
 
+      # Signs an HTTP message.
+      #
+      # Creates a signature by:
+      # 1. Serializing the component identifiers
+      # 2. Building the signature base from the message and parameters
+      # 3. Signing the signature base with the key
+      # 4. Returning a Signature object with the result
+      #
+      # @param key [Linzer::Key] The private key to sign with. Must respond to
+      #   `#sign` and should contain private key material.
+      # @param message [Linzer::Message] The HTTP message to sign
+      # @param components [Array<String>] Component identifiers to include in
+      #   the signature. Can be header names (e.g., `"content-type"`) or derived
+      #   components (e.g., `"@method"`, `"@path"`). May include parameters
+      #   (e.g., `"content-type";bs` for binary-wrapped).
+      # @param options [Hash] Additional signature parameters
+      # @option options [Integer] :created Unix timestamp for signature creation.
+      #   Defaults to the current UTC time.
+      # @option options [String] :keyid Key identifier. If not provided, uses
+      #   the key's `key_id` if available.
+      # @option options [String] :label The signature label (defaults to "sig1").
+      #   Multiple signatures on a message must have distinct labels.
+      # @option options [String] :nonce A unique nonce value to prevent replay
+      # @option options [String] :tag Application-specific tag
+      # @option options [Integer] :expires Unix timestamp when signature expires
+      # @option options [String] :alg Algorithm identifier (usually inferred from key)
+      #
+      # @return [Linzer::Signature] The generated signature, ready to be attached
+      #   to the message via {Signature#to_h}
+      #
+      # @raise [SigningError] If the message, key, or components are invalid
+      # @raise [SigningError] If required components are missing from the message
+      # @raise [SigningError] If components are duplicated
+      # @raise [SigningError] If `@signature-params` is included in components
+      #
+      # @example Basic signing
+      #   signature = Linzer::Signer.sign(key, message, %w[@method @path])
+      #
+      # @example With all options
+      #   signature = Linzer::Signer.sign(key, message, %w[@method @path date],
+      #     created: Time.now.to_i,
+      #     keyid: "my-key-2024",
+      #     label: "request-sig",
+      #     nonce: SecureRandom.hex(16),
+      #     tag: "my-app"
+      #   )
       def sign(key, message, components, options = {})
         serialized_components = FieldId.serialize_components(Array(components))
         validate key, message, serialized_components
@@ -20,12 +80,17 @@ module Linzer
         Linzer::Signature.build(serialize(signature, serialized_components, parameters, label))
       end
 
+      # Returns the default signature label.
+      #
+      # @return [String] The default label ("sig1")
       def default_label
         DEFAULT_LABEL
       end
 
       private
 
+      # Validates signing inputs.
+      # @raise [SigningError] If any input is invalid
       def validate(key, message, components)
         msg = "Message cannot be signed with null %s"
         raise SigningError, msg % "value"     if message.nil?
@@ -39,6 +104,8 @@ module Linzer
         end
       end
 
+      # Builds the signature parameters hash from options and key.
+      # @return [Hash] The populated parameters
       def populate_parameters(key, options)
         parameters = {}
 
@@ -52,6 +119,8 @@ module Linzer
         parameters
       end
 
+      # Serializes the signature into HTTP header format.
+      # @return [Hash] Hash with "signature" and "signature-input" keys
       def serialize(signature, components, parameters, label)
         {
           "signature" => Starry.serialize({label => signature}),