linzer 0.7.7 → 0.7.8

data/lib/linzer/verifier.rb

@@ -1,10 +1,57 @@
 # frozen_string_literal: true
 
 module Linzer
+  # Handles HTTP message signature verification according to RFC 9421.
+  #
+  # This module verifies that a signature on an HTTP message is valid by:
+  # 1. Reconstructing the signature base from the message and signature parameters
+  # 2. Verifying the signature using the provided public key
+  #
+  # @example Direct usage (prefer Linzer.verify for convenience)
+  #   signature = Linzer::Signature.build(signature_headers)
+  #   message = Linzer::Message.new(request)
+  #   Linzer::Verifier.verify(pubkey, message, signature)
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-3.2 RFC 9421 Section 3.2
   module Verifier
     class << self
       include Common
 
+      # Verifies an HTTP message signature.
+      #
+      # Verification succeeds if:
+      # - 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 is not older than `no_older_than` (if specified)
+      #
+      # @param key [Linzer::Key] The public key to verify with. Must respond to
+      #   `#verify` and should contain public key material.
+      # @param message [Linzer::Message] The HTTP message to verify
+      # @param signature [Linzer::Signature] The signature to verify. Typically
+      #   built from the `signature` and `signature-input` headers using
+      #   {Signature.build}.
+      # @param no_older_than [Integer, nil] Maximum age in seconds. If the
+      #   signature's `created` parameter is older than this, verification fails.
+      #   This helps mitigate replay attacks. See RFC 9421 Section 7.2.2.
+      #
+      # @return [true] Returns true if verification succeeds
+      #
+      # @raise [VerifyError] If the message is nil
+      # @raise [VerifyError] If the key is nil
+      # @raise [VerifyError] If the signature is nil or invalid
+      # @raise [VerifyError] If required components are missing from the message
+      # @raise [VerifyError] If the signature is too old (when no_older_than is set)
+      # @raise [VerifyError] If the cryptographic verification fails
+      #
+      # @example Basic verification
+      #   Linzer::Verifier.verify(pubkey, message, signature)
+      #   # => true (or raises VerifyError)
+      #
+      # @example With age validation (5 minute window)
+      #   Linzer::Verifier.verify(pubkey, message, signature, no_older_than: 300)
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-7.2.2 Signature Replay
       def verify(key, message, signature, no_older_than: nil)
         validate message, key, signature, no_older_than: no_older_than
 
@@ -18,6 +65,8 @@ module Linzer
 
       private
 
+      # Validates all verification inputs before attempting verification.
+      # @raise [VerifyError] If any input is invalid or signature is too old
       def validate(message, key, signature, no_older_than: nil)
         raise VerifyError, "Message to verify cannot be null"       if message.nil?
         raise VerifyError, "Key to verify signature cannot be null" if key.nil?
@@ -45,6 +94,9 @@ module Linzer
         end
       end
 
+      # Performs cryptographic verification and raises on failure.
+      # @return [true] If verification succeeds
+      # @raise [VerifyError] If verification fails
       def verify_or_fail(key, signature, data)
         return true if key.verify(signature, data)
         raise VerifyError, "Failed to verify message: Invalid signature."

data/lib/linzer/version.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
 module Linzer
-  VERSION = "0.7.7"
+  # Current version of the Linzer gem.
+  # @return [String]
+  VERSION = "0.7.8"
 end

data/lib/linzer.rb

@@ -28,30 +28,134 @@ require_relative "linzer/signer"
 require_relative "linzer/verifier"
 require_relative "linzer/http"
 
+# Linzer is a Ruby library for HTTP Message Signatures as defined in RFC 9421.
+#
+# It provides functionality to sign and verify HTTP messages using various
+# cryptographic algorithms including RSA-PSS, HMAC-SHA256, ECDSA, and Ed25519.
+#
+# @example Signing a request with Ed25519
+#   key = Linzer.generate_ed25519_key("my-key-id")
+#   request = Net::HTTP::Post.new(URI("https://example.com/api"))
+#   request["date"] = Time.now.httpdate
+#
+#   Linzer.sign!(request,
+#     key: key,
+#     components: %w[@method @request-target date]
+#   )
+#
+# @example Verifying a signed request
+#   pubkey = Linzer.new_ed25519_public_key(public_key_pem, "my-key-id")
+#   Linzer.verify!(request, key: pubkey)
+#
+# @see https://www.rfc-editor.org/rfc/rfc9421.html RFC 9421 - HTTP Message Signatures
+# @see https://github.com/nomadium Author on GitHub
+# @author Miguel Landaeta
 module Linzer
+  # Base error class for all Linzer errors.
+  # @see VerifyError
+  # @see SigningError
   class Error < StandardError; end
 
+  # Raised when signature verification fails.
+  #
+  # @example Handling verification errors
+  #   begin
+  #     Linzer.verify(pubkey, message, signature)
+  #   rescue Linzer::VerifyError => e
+  #     puts "Verification failed: #{e.message}"
+  #   end
   class VerifyError < Error; end
 
+  # Raised when message signing fails.
+  #
+  # @example Handling signing errors
+  #   begin
+  #     Linzer.sign(key, message, components)
+  #   rescue Linzer::SigningError => e
+  #     puts "Signing failed: #{e.message}"
+  #   end
   class SigningError < Error; end
 
   class << self
     include Key::Helper
     include Helper
 
+    # Verifies an HTTP message signature.
+    #
+    # @param pubkey [Linzer::Key] The public key to verify the signature with
+    # @param message [Linzer::Message] The HTTP message to verify
+    # @param signature [Linzer::Signature] The signature to verify
+    # @param no_older_than [Integer, nil] Maximum age of signature in seconds.
+    #   If provided, signatures with a `created` timestamp older than this
+    #   value will be rejected to mitigate replay attacks.
+    #
+    # @return [true] Returns true if verification succeeds
+    # @raise [VerifyError] If verification fails for any reason
+    #
+    # @example Basic verification
+    #   Linzer.verify(pubkey, message, signature)
+    #
+    # @example Verification with age limit (reject signatures older than 5 minutes)
+    #   Linzer.verify(pubkey, message, signature, no_older_than: 300)
+    #
+    # @see Linzer::Verifier.verify
     def verify(pubkey, message, signature, no_older_than: nil)
       Linzer::Verifier.verify(pubkey, message, signature, no_older_than: no_older_than)
     end
 
+    # Signs an HTTP message.
+    #
+    # @param key [Linzer::Key] The private key to sign with
+    # @param message [Linzer::Message] The HTTP message to sign
+    # @param components [Array<String>] The message components to include in
+    #   the signature (e.g., `["@method", "@path", "content-type"]`)
+    # @param options [Hash] Additional signature parameters
+    # @option options [Integer] :created Unix timestamp for signature creation
+    #   (defaults to current time)
+    # @option options [String] :keyid Key identifier to include in signature
+    # @option options [String] :label Signature label (defaults to "sig1")
+    # @option options [String] :nonce A unique nonce value
+    # @option options [String] :tag Application-specific tag
+    # @option options [Integer] :expires Unix timestamp for signature expiration
+    #
+    # @return [Linzer::Signature] The generated signature
+    # @raise [SigningError] If signing fails
+    #
+    # @example Sign with default options
+    #   signature = Linzer.sign(key, message, %w[@method @path date])
+    #
+    # @example Sign with custom parameters
+    #   signature = Linzer.sign(key, message, %w[@method @path],
+    #     keyid: "my-key",
+    #     created: Time.now.to_i,
+    #     nonce: SecureRandom.hex(16)
+    #   )
+    #
+    # @see Linzer::Signer.sign
     def sign(key, message, components, options = {})
       Linzer::Signer.sign(key, message, components, options)
     end
 
+    # Computes the signature base string for an HTTP message.
+    #
+    # The signature base is the canonical string representation that gets
+    # signed. This method is primarily useful for debugging or implementing
+    # custom signing logic.
+    #
+    # @param message [Linzer::Message] The HTTP message
+    # @param components [Array<String>] Serialized component identifiers
+    # @param parameters [Hash] Signature parameters
+    #
+    # @return [String] The signature base string
+    #
+    # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-2.5 RFC 9421 Section 2.5
     def signature_base(message, components, parameters)
       Linzer::Common.signature_base(message, components, parameters)
     end
   end
 
+  # Alias for {Message::Field::Identifier} for convenient access.
+  # Used for serializing and deserializing component identifiers.
   FieldId = Message::Field::Identifier
 end
 

data/lib/rack/auth/signature.rb

@@ -4,23 +4,96 @@ require "linzer"
 require "logger"
 require_relative "signature/helpers"
 
-# Rack::Auth::Signature implements HTTP Message Signatures, as per RFC 9421.
-#
-# Initialize with the Rack application that you want protecting.
-# A hash with options and a block can be passed to customize, enhance
-# or disable security checks applied to incoming requests.
-#
 module Rack
   module Auth
+    # Rack middleware for HTTP Message Signature verification (RFC 9421).
+    #
+    # This middleware verifies that incoming requests have valid HTTP signatures.
+    # Requests without valid signatures are rejected with a 401 Unauthorized response.
+    #
+    # @example Basic usage in config.ru
+    #   require "linzer"
+    #
+    #   use Rack::Auth::Signature,
+    #     except: "/health",
+    #     default_key: {
+    #       material: File.read("public_key.pem"),
+    #       alg: "ed25519"
+    #     }
+    #
+    #   run MyApp
+    #
+    # @example With configuration file
+    #   use Rack::Auth::Signature,
+    #     except: ["/login", "/health"],
+    #     config_path: "config/http-signatures.yml"
+    #
+    # @example In a Rails application (config/application.rb)
+    #   config.middleware.use Rack::Auth::Signature,
+    #     except: "/login",
+    #     config_path: "config/http-signatures.yml"
+    #
+    # @example With a block for custom configuration
+    #   use Rack::Auth::Signature do
+    #     # Custom configuration via instance_eval
+    #   end
+    #
+    # Configuration file format (YAML):
+    #
+    #   signatures:
+    #     reject_older_than: 900        # Reject signatures older than 15 minutes
+    #     created_required: true        # Require 'created' parameter
+    #     keyid_required: false         # Require 'keyid' parameter
+    #     covered_components:           # Required components in signature
+    #       - "@method"
+    #       - "@request-target"
+    #       - "date"
+    #   keys:
+    #     my-key-id:
+    #       alg: ed25519
+    #       material: |                 # Inline PEM
+    #         -----BEGIN PUBLIC KEY-----
+    #         ...
+    #         -----END PUBLIC KEY-----
+    #     other-key:
+    #       alg: rsa-pss-sha512
+    #       path: keys/public.pem       # Or path to key file
+    #
+    # @see https://www.rfc-editor.org/rfc/rfc9421.html RFC 9421
+    # @see Helpers::Configuration For configuration options
+    # @see Helpers::Key For key lookup behavior
     class Signature
       include Helpers
 
+      # Creates a new signature verification middleware.
+      #
+      # @param app [#call] The Rack application to protect
+      # @param options [Hash] Configuration options
+      # @option options [String, Array<String>] :except Paths to exclude from
+      #   signature verification (e.g., "/login", "/health")
+      # @option options [String] :config_path Path to YAML configuration file
+      # @option options [Hash] :default_key Default key configuration when
+      #   keyid is not present or not found in keys hash
+      # @option options [Hash] :keys Hash of key configurations keyed by keyid
+      # @option options [Hash] :signatures Signature verification options
+      #
+      # @yield Optional block for additional configuration via instance_eval
       def initialize(app, options = {}, &block)
         @app = app
         @options = load_options(Hash(options))
         instance_eval(&block) if block
       end
 
+      # Processes an incoming request.
+      #
+      # If the request path is excluded or the signature is valid, the request
+      # is passed to the wrapped application. Otherwise, returns a 401 response.
+      #
+      # On successful verification, the signature is stored in `env["rack.signature"]`
+      # for use by the application.
+      #
+      # @param env [Hash] The Rack environment
+      # @return [Array] Rack response tuple [status, headers, body]
       def call(env)
         @request = Rack::Request.new(env)
 
@@ -34,25 +107,30 @@ module Rack
 
       private
 
+      # Checks if the current request path is excluded from verification.
       def excluded?
         return false if !request
         Array(options[:except]).include?(request.path_info)
       end
 
+      # Checks if the request should be allowed (has valid signature).
       def allowed?
         has_signature? && acceptable? && verifiable?
       end
 
       attr_reader :request, :options
 
+      # Returns the signature parameters.
       def params
         @signature.parameters || {}
       end
 
+      # Returns the logger instance.
       def logger
         @logger ||= request.logger || ::Logger.new($stderr)
       end
 
+      # Checks if the request has signature headers.
       def has_signature?
         @signature = build_signature
         (@signature.to_h.keys & %w[signature signature-input]).size == 2
@@ -61,6 +139,7 @@ module Rack
         false
       end
 
+      # Builds a Signature object from request headers.
       def build_signature
         signature_opts = {}
         label = options[:signatures][:default_label]
@@ -77,6 +156,7 @@ module Rack
         signature
       end
 
+      # Checks if required signature parameters are present.
       def has_required_params?
         created? && expires? && keyid? && nonce? && alg? && tag?
       rescue => ex
@@ -84,6 +164,7 @@ module Rack
         false
       end
 
+      # Checks if required components are covered by the signature.
       def has_required_components?
         components         = @signature.serialized_components || []
         covered_components = options[:signatures][:covered_components]
@@ -92,10 +173,12 @@ module Rack
         (covered_components || []).all? { |c| components.include?(c) }
       end
 
+      # Checks if the signature meets all requirements.
       def acceptable?
         has_required_params? && has_required_components?
       end
 
+      # Verifies the signature cryptographically.
       def verifiable?
         verify_opts = build_and_check_verify_opts || {}
         Linzer.verify(key, @message, @signature, **verify_opts)
@@ -104,6 +187,7 @@ module Rack
         false
       end
 
+      # Builds verification options and logs warnings for security issues.
       def build_and_check_verify_opts
         verify_opts = {}
         reject_older = options[:signatures][:reject_older_than]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: linzer
 version: !ruby/object:Gem::Version
-  version: 0.7.7
+  version: 0.7.8
 platform: ruby
 authors:
 - Miguel Landaeta
@@ -13,22 +13,22 @@ dependencies:
   name: openssl
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: '3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: starry
   requirement: !ruby/object:Gem::Requirement
@@ -147,30 +147,42 @@ dependencies:
   name: net-http
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: '0.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.6.0
+        version: '0.6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.10'
 - !ruby/object:Gem::Dependency
   name: cgi
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.4.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: 0.4.2
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.6.0
 email:
 - miguel@miguel.cc
 executables: []
@@ -188,6 +200,8 @@ files:
 - examples/sinatra/config.ru
 - examples/sinatra/http-signatures.yml
 - examples/sinatra/myapp.rb
+- flake.lock
+- flake.nix
 - lib/linzer.rb
 - lib/linzer/common.rb
 - lib/linzer/ecdsa.rb
@@ -245,7 +259,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.8
 specification_version: 4
 summary: An implementation of HTTP Messages Signatures (RFC9421)
 test_files: []