linzer 0.7.7 → 0.7.8

data/lib/linzer/http/signature_feature.rb

@@ -5,6 +5,8 @@ require_relative "bootstrap"
 module Linzer
   module HTTP
     class << self
+      # Registers the HTTP gem request adapter.
+      # @api private
       def register_adapter
         request_class = ::HTTP::Request
         adapter_class = Linzer::Message::Adapter::HTTPGem::Request
@@ -15,15 +17,62 @@ module Linzer
     Bootstrap.load_dependencies
     register_adapter
 
+    # HTTP.rb gem feature for automatic request signing.
+    #
+    # This feature integrates with the http.rb gem to automatically sign
+    # outgoing HTTP requests. It wraps each request before sending and
+    # adds the `signature` and `signature-input` headers.
+    #
+    # @note This file must be explicitly required:
+    #   `require "linzer/http/signature_feature"`
+    #
+    # @example Basic usage
+    #   require "linzer/http/signature_feature"
+    #
+    #   key = Linzer.generate_ed25519_key("my-key")
+    #   response = HTTP
+    #     .use(http_signature: { key: key })
+    #     .get("https://example.com/api")
+    #
+    # @example With custom components and parameters
+    #   response = HTTP
+    #     .use(http_signature: {
+    #       key: key,
+    #       covered_components: %w[@method @authority @path date],
+    #       params: { nonce: SecureRandom.hex(16) }
+    #     })
+    #     .post("https://example.com/api", json: { data: "value" })
+    #
+    # @see https://github.com/httprb/http http.rb gem
     class SignatureFeature < ::HTTP::Feature
+      # Creates a new signature feature.
+      #
+      # @param key [Linzer::Key] The signing key (required)
+      # @param params [Hash] Additional signature parameters
+      #   (created, nonce, tag, etc.)
+      # @param covered_components [Array<String>] Components to include
+      #   in the signature. Defaults to `@method`, `@request-target`,
+      #   `@authority`, and `date`.
+      #
+      # @raise [HTTP::Error] If key is nil or invalid
       def initialize(key:, params: {}, covered_components: default_components)
         @fields = Array(covered_components)
         @key    = validate_key(key)
         @params = Hash(params)
       end
 
-      attr_reader :fields, :params
+      # @return [Array<String>] The components to include in signatures
+      attr_reader :fields
 
+      # @return [Hash] Additional signature parameters
+      attr_reader :params
+
+      # Wraps an outgoing request to add signature headers.
+      #
+      # Called automatically by http.rb for each request.
+      #
+      # @param request [HTTP::Request] The outgoing request
+      # @return [HTTP::Request] The request with signature headers added
       def wrap_request(request)
         message   = Linzer::Message.new(request)
         signature = Linzer.sign(key, message, fields, **params)
@@ -31,6 +80,8 @@ module Linzer
         request
       end
 
+      # Returns the default covered components.
+      # @return [Array<String>] Default components from {Options::DEFAULT}
       def default_covered_components
         Linzer::Options::DEFAULT[:covered_components]
       end
@@ -47,6 +98,7 @@ module Linzer
         key
       end
 
+      # Register this feature with http.rb
       ::HTTP::Options.register_feature(:http_signature, self)
     end
   end

data/lib/linzer/http.rb

@@ -3,9 +3,38 @@
 require "net/http"
 
 module Linzer
+  # Simple HTTP client with automatic request signing.
+  #
+  # This module provides convenience methods for making signed HTTP requests
+  # using Net::HTTP. It automatically signs outgoing requests with the
+  # provided key.
+  #
+  # For each standard HTTP method (GET, POST, PUT, DELETE, etc.), a
+  # corresponding method is dynamically defined.
+  #
+  # @example Making a signed GET request
+  #   key = Linzer.generate_ed25519_key("my-key")
+  #   response = Linzer::HTTP.get("https://example.com/api", key: key)
+  #
+  # @example Making a signed POST request with body
+  #   response = Linzer::HTTP.post("https://example.com/api",
+  #     key: key,
+  #     data: { "name" => "value" }.to_json,
+  #     headers: { "Content-Type" => "application/json" }
+  #   )
+  #
+  # @example Customizing covered components
+  #   response = Linzer::HTTP.get("https://example.com/api",
+  #     key: key,
+  #     covered_components: %w[@method @authority @path date content-type]
+  #   )
+  #
+  # @see SignatureFeature For http.rb gem integration
   module HTTP
     extend self
 
+    # Returns the list of known HTTP methods from Net::HTTP.
+    # @return [Array<String>] HTTP method names (e.g., "GET", "POST")
     def self.known_http_methods
       Net::HTTP
         .constants
@@ -15,6 +44,29 @@ module Linzer
         .freeze
     end
 
+    # Dynamically define methods for each HTTP verb (get, post, put, etc.)
+    #
+    # @!method get(uri, options)
+    #   Makes a signed GET request.
+    #   @param uri [String] The request URI
+    #   @param options [Hash] Request options
+    #   @option options [Key] :key The signing key (required)
+    #   @option options [Hash] :headers Additional headers
+    #   @option options [Array<String>] :covered_components Components to sign
+    #   @option options [Hash] :params Additional signature parameters
+    #   @option options [Boolean] :debug Enable debug output
+    #   @return [Net::HTTPResponse] The response
+    #
+    # @!method post(uri, options)
+    #   Makes a signed POST request.
+    #   @param uri [String] The request URI
+    #   @param options [Hash] Request options
+    #   @option options [Key] :key The signing key (required)
+    #   @option options [String] :data Request body (required for POST)
+    #   @option options [Hash] :headers Additional headers
+    #   @option options [Array<String>] :covered_components Components to sign
+    #   @option options [Hash] :params Additional signature parameters
+    #   @return [Net::HTTPResponse] The response
     known_http_methods.each do |http_method|  # e.g.:
       method = http_method.downcase.to_sym    #
       define_method(method) do |uri, options| # def post(uri, **options)
@@ -25,6 +77,7 @@ module Linzer
 
     private
 
+    # Executes a signed HTTP request.
     def request(verb, uri, options = {})
       validate_verb(verb)
 
@@ -76,6 +129,7 @@ module Linzer
       request
     end
 
+    # Determines if the HTTP method typically has a request body.
     def with_body?(verb)
       # common HTTP
       return false if %i[get head options trace delete].include?(verb)

data/lib/linzer/jws.rb

@@ -5,13 +5,58 @@ require "jwt/eddsa"
 require "ed25519"
 
 module Linzer
+  # JSON Web Signature (JWS) compatible key support.
+  #
+  # This module provides integration with the jwt gem for working with
+  # JWK (JSON Web Key) format keys. It enables interoperability with
+  # systems using JWS/JWT standards.
+  #
+  # Currently supports:
+  # - EdDSA (Ed25519)
+  #
+  # @note This module requires the `jwt` and `ed25519` gems.
+  #
+  # @example Generating a JWS-compatible EdDSA key
+  #   key = Linzer.generate_jws_key(algorithm: "EdDSA")
+  #
+  # @example Importing from JWK format
+  #   jwk = {
+  #     "kty" => "OKP",
+  #     "crv" => "Ed25519",
+  #     "x" => "...",
+  #     "d" => "..."  # private key component (optional)
+  #   }
+  #   key = Linzer.jwk_import(jwk)
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc7517 RFC 7517 - JSON Web Key (JWK)
+  # @see https://www.rfc-editor.org/rfc/rfc8037 RFC 8037 - EdDSA for JWS/JWK
   module JWS
+    # Imports a key from JWK (JSON Web Key) format.
+    #
+    # @param key [Hash] The JWK as a Hash with string keys
+    # @param params [Hash] Additional key parameters
+    # @option params [String] :id Key identifier (overrides JWK "kid" if present)
+    # @return [JWS::Key] The imported key
+    # @raise [Error] If the JWK format is invalid or algorithm unsupported
+    #
+    # @example
+    #   jwk = JSON.parse(File.read("key.jwk"))
+    #   key = Linzer::JWS.jwk_import(jwk, id: "my-key-id")
     def jwk_import(key, params = {})
       material = JWT::JWK.import(key)
       Linzer::JWS::Key.new(material, params)
     end
     module_function :jwk_import
 
+    # Generates a new JWS-compatible key pair.
+    #
+    # @param algorithm [String] The JWS algorithm identifier.
+    #   Currently only "EdDSA" is supported.
+    # @return [JWS::Key] A new key pair
+    # @raise [Error] If the algorithm is not supported
+    #
+    # @example
+    #   key = Linzer::JWS.generate_key(algorithm: "EdDSA")
     def generate_key(algorithm:)
       case String(algorithm)
       when "EdDSA"
@@ -25,25 +70,52 @@ module Linzer
     end
     module_function :generate_key
 
+    # JWS-compatible signing key implementation.
+    #
+    # Wraps a JWT::JWK key object to provide the Linzer Key interface.
+    # This enables using JWK-format keys with HTTP Message Signatures.
+    #
+    # @see Linzer::Key::Helper#generate_jws_key
+    # @see Linzer::Key::Helper#jwk_import
     class Key < Linzer::Key
+      # Signs data using the JWS key.
+      #
+      # @param data [String] The data to sign
+      # @return [String] The signature bytes
+      # @raise [SigningError] If this key cannot be used for signing
       def sign(data)
         validate_signing_key
         algo = resolve_algorithm
         algo.sign(data: data, signing_key: signing_key)
       end
 
+      # Verifies a signature using the JWS key.
+      #
+      # @param signature [String] The signature bytes to verify
+      # @param data [String] The data that was signed
+      # @return [Boolean] true if valid, false otherwise
+      # @raise [VerifyError] If this key cannot be used for verification
       def verify(signature, data)
         validate_verify_key
         algo = resolve_algorithm
         algo.verify(data: data, signature: signature, verification_key: verify_key)
       end
 
+      # @return [Boolean] true if this key can verify signatures
       def public?
         !!verify_key
       end
 
+      # @return [Boolean] true if this key can create signatures
+      def private?
+        !!signing_key
+      end
+
       private
 
+      # Resolves the appropriate JWT algorithm implementation.
+      # @return [JWT::JWA::SigningAlgorithm] The algorithm implementation
+      # @raise [Error] If the algorithm cannot be determined
       def resolve_algorithm
         case
         when material.verify_key.is_a?(::Ed25519::VerifyKey)
@@ -53,10 +125,12 @@ module Linzer
         end
       end
 
+      # @return [Ed25519::VerifyKey, nil] The verification key
       def verify_key
         material.verify_key
       end
 
+      # @return [Ed25519::SigningKey, nil] The signing key
       def signing_key
         material.signing_key
       end

data/lib/linzer/key/helper.rb

@@ -2,94 +2,270 @@
 
 module Linzer
   class Key
+    # Helper methods for generating and loading cryptographic keys.
+    #
+    # These methods provide convenient factory functions for creating
+    # {Linzer::Key} instances for various algorithms. They are mixed into
+    # the {Linzer} module and can be called directly.
+    #
+    # @example Generating keys
+    #   ed25519_key = Linzer.generate_ed25519_key("my-key")
+    #   hmac_key = Linzer.generate_hmac_sha256_key("hmac-key")
+    #   ecdsa_key = Linzer.generate_ecdsa_p256_sha256_key("ecdsa-key")
+    #
+    # @example Loading keys from PEM
+    #   key = Linzer.new_ed25519_key(File.read("private.pem"), "my-key")
+    #   pubkey = Linzer.new_ed25519_public_key(File.read("public.pem"), "my-key")
+    #
+    # @see Key
     module Helper
+      # Generates a new RSA-PSS key pair with SHA-512 digest.
+      #
+      # RSA-PSS (RSASSA-PSS) is the recommended RSA signature scheme.
+      # Uses the `rsa-pss-sha512` algorithm identifier.
+      #
+      # @param size [Integer] Key size in bits (ignored, uses OpenSSL default)
+      # @param key_id [String, nil] Optional key identifier
+      # @return [RSAPSS::Key] A new RSA-PSS key pair
+      #
+      # @example
+      #   key = Linzer.generate_rsa_pss_sha512_key(2048, "my-rsa-key")
       def generate_rsa_pss_sha512_key(size, key_id = nil)
         material = OpenSSL::PKey.generate_key("RSASSA-PSS")
         Linzer::RSAPSS::Key.new(material, id: key_id, digest: "SHA512")
       end
 
+      # Loads an RSA-PSS key from PEM-encoded material.
+      #
+      # Can load either a private key (for signing) or public key (for verification).
+      #
+      # @param material [String] PEM-encoded RSA key
+      # @param key_id [String, nil] Optional key identifier
+      # @return [RSAPSS::Key] The loaded key
+      #
+      # @example Loading a private key
+      #   key = Linzer.new_rsa_pss_sha512_key(File.read("private.pem"), "my-key")
+      #
+      # @example Loading a public key
+      #   pubkey = Linzer.new_rsa_pss_sha512_key(File.read("public.pem"), "my-key")
       def new_rsa_pss_sha512_key(material, key_id = nil)
         key = OpenSSL::PKey.read(material)
         Linzer::RSAPSS::Key.new(key, id: key_id, digest: "SHA512")
       end
 
-      # XXX: investigate: was this method made redundant after:
-      # https://github.com/nomadium/linzer/pull/10
+      # Loads an RSA-PSS public key from PEM-encoded material.
+      #
+      # @deprecated Use {#new_rsa_pss_sha512_key} instead, which handles both
+      #   public and private keys.
+      # @param material [String] PEM-encoded RSA public key
+      # @param key_id [String, nil] Optional key identifier
+      # @return [RSAPSS::Key] The loaded public key
       def new_rsa_pss_sha512_public_key(material, key_id = nil)
         key = OpenSSL::PKey::RSA.new(material)
         Linzer::RSAPSS::Key.new(key, id: key_id, digest: "SHA512")
       end
 
+      # Generates a new RSA PKCS#1 v1.5 key pair with SHA-256 digest.
+      #
+      # @note RSA-PSS is preferred for new applications. Use this only for
+      #   compatibility with systems requiring PKCS#1 v1.5.
+      #
+      # Uses the `rsa-v1_5-sha256` algorithm identifier.
+      #
+      # @param size [Integer] Key size in bits (e.g., 2048, 4096)
+      # @param key_id [String, nil] Optional key identifier
+      # @return [RSA::Key] A new RSA key pair
+      #
+      # @example
+      #   key = Linzer.generate_rsa_v1_5_sha256_key(2048, "legacy-rsa")
       def generate_rsa_v1_5_sha256_key(size, key_id = nil)
         material = OpenSSL::PKey::RSA.generate(size)
         Linzer::RSA::Key.new(material, id: key_id, digest: "SHA256")
       end
 
+      # Loads an RSA PKCS#1 v1.5 key from PEM-encoded material.
+      #
+      # @param material [String] PEM-encoded RSA key
+      # @param key_id [String, nil] Optional key identifier
+      # @return [RSA::Key] The loaded key
       def new_rsa_v1_5_sha256_key(material, key_id = nil)
         key = OpenSSL::PKey.read(material)
         Linzer::RSA::Key.new(key, id: key_id, digest: "SHA256")
       end
 
-      # XXX: investigate: was this method made redundant after:
-      # https://github.com/nomadium/linzer/pull/10
+      # Loads an RSA PKCS#1 v1.5 public key from PEM-encoded material.
+      #
+      # @deprecated Use {#new_rsa_v1_5_sha256_key} instead.
+      # @param material [String] PEM-encoded RSA public key
+      # @param key_id [String, nil] Optional key identifier
+      # @return [RSA::Key] The loaded public key
       def new_rsa_v1_5_sha256_public_key(material, key_id = nil)
         key = OpenSSL::PKey.read(material)
         Linzer::RSA::Key.new(key, id: key_id, digest: "SHA256")
       end
 
+      # Generates a new HMAC-SHA256 symmetric key.
+      #
+      # HMAC keys are symmetric, meaning the same key is used for both
+      # signing and verification. The key material must be kept secret.
+      #
+      # Uses the `hmac-sha256` algorithm identifier.
+      #
+      # @param key_id [String, nil] Optional key identifier
+      # @return [HMAC::Key] A new 64-byte random HMAC key
+      #
+      # @example
+      #   key = Linzer.generate_hmac_sha256_key("shared-secret")
       def generate_hmac_sha256_key(key_id = nil)
         material = OpenSSL::Random.random_bytes(64)
         Linzer::HMAC::Key.new(material, id: key_id, digest: "SHA256")
       end
 
+      # Creates an HMAC-SHA256 key from existing key material.
+      #
+      # @param material [String] The secret key bytes (should be at least 32 bytes)
+      # @param key_id [String, nil] Optional key identifier
+      # @return [HMAC::Key] The HMAC key
+      #
+      # @example Loading from environment
+      #   key = Linzer.new_hmac_sha256_key(
+      #     Base64.decode64(ENV["HMAC_SECRET"]),
+      #     "api-key"
+      #   )
       def new_hmac_sha256_key(material, key_id = nil)
         Linzer::HMAC::Key.new(material, id: key_id, digest: "SHA256")
       end
 
+      # Generates a new Ed25519 key pair.
+      #
+      # Ed25519 is a modern elliptic curve signature algorithm that provides
+      # excellent security and performance. Recommended for new applications.
+      #
+      # Uses the `ed25519` algorithm identifier.
+      #
+      # @param key_id [String, nil] Optional key identifier
+      # @return [Ed25519::Key] A new Ed25519 key pair
+      #
+      # @example
+      #   key = Linzer.generate_ed25519_key("my-ed25519-key")
       def generate_ed25519_key(key_id = nil)
         material = OpenSSL::PKey.generate_key("ed25519")
         Linzer::Ed25519::Key.new(material, id: key_id)
       end
 
+      # Loads an Ed25519 key from PEM-encoded material.
+      #
+      # Can load either a private key (for signing) or public key (for verification).
+      #
+      # @param material [String] PEM-encoded Ed25519 key
+      # @param key_id [String, nil] Optional key identifier
+      # @return [Ed25519::Key] The loaded key
+      #
+      # @example Loading a private key for signing
+      #   key = Linzer.new_ed25519_key(File.read("ed25519.pem"), "my-key")
       def new_ed25519_key(material, key_id = nil)
         key = OpenSSL::PKey.read(material)
         Linzer::Ed25519::Key.new(key, id: key_id)
       end
 
+      # Loads an Ed25519 public key from PEM-encoded material.
+      #
+      # This is an alias for {#new_ed25519_key} for clarity when loading
+      # public keys specifically.
+      #
+      # @param material [String] PEM-encoded Ed25519 public key
+      # @param key_id [String, nil] Optional key identifier
+      # @return [Ed25519::Key] The loaded public key
+      #
+      # @example
+      #   pubkey = Linzer.new_ed25519_public_key(File.read("ed25519_pub.pem"), "my-key")
       def new_ed25519_public_key(material, key_id = nil)
         new_ed25519_key(material, key_id)
       end
 
-      # https://www.rfc-editor.org/rfc/rfc4492.html#appendix-A
-      # Table 6: Equivalent curves defined by SECG, ANSI, and NIST
-      # secp256r1   |  prime256v1   |   NIST P-256
+      # Generates a new ECDSA P-256 key pair with SHA-256 digest.
+      #
+      # ECDSA P-256 (also known as secp256r1 or prime256v1) is widely supported
+      # and provides good security for most applications.
+      #
+      # Uses the `ecdsa-p256-sha256` algorithm identifier.
+      #
+      # @param key_id [String, nil] Optional key identifier
+      # @return [ECDSA::Key] A new ECDSA P-256 key pair
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc4492.html#appendix-A RFC 4492 Appendix A
+      #
+      # @example
+      #   key = Linzer.generate_ecdsa_p256_sha256_key("ecdsa-key")
       def generate_ecdsa_p256_sha256_key(key_id = nil)
         material = OpenSSL::PKey::EC.generate("prime256v1")
         Linzer::ECDSA::Key.new(material, id: key_id, digest: "SHA256")
       end
 
+      # Loads an ECDSA P-256 key from PEM-encoded material.
+      #
+      # @param material [String] PEM-encoded EC key
+      # @param key_id [String, nil] Optional key identifier
+      # @return [ECDSA::Key] The loaded key
       def new_ecdsa_p256_sha256_key(material, key_id = nil)
         key = OpenSSL::PKey::EC.new(material)
         Linzer::ECDSA::Key.new(key, id: key_id, digest: "SHA256")
       end
 
-      # https://www.rfc-editor.org/rfc/rfc4492.html#appendix-A
-      # Table 6: Equivalent curves defined by SECG, ANSI, and NIST
-      # secp384r1   |               |   NIST P-384
+      # Generates a new ECDSA P-384 key pair with SHA-384 digest.
+      #
+      # ECDSA P-384 (also known as secp384r1) provides higher security than P-256
+      # at the cost of larger signatures and slightly slower operations.
+      #
+      # Uses the `ecdsa-p384-sha384` algorithm identifier.
+      #
+      # @param key_id [String, nil] Optional key identifier
+      # @return [ECDSA::Key] A new ECDSA P-384 key pair
+      #
+      # @see https://www.rfc-editor.org/rfc/rfc4492.html#appendix-A RFC 4492 Appendix A
+      #
+      # @example
+      #   key = Linzer.generate_ecdsa_p384_sha384_key("high-security-key")
       def generate_ecdsa_p384_sha384_key(key_id = nil)
         material = OpenSSL::PKey::EC.generate("secp384r1")
         Linzer::ECDSA::Key.new(material, id: key_id, digest: "SHA384")
       end
 
+      # Loads an ECDSA P-384 key from PEM-encoded material.
+      #
+      # @param material [String] PEM-encoded EC key
+      # @param key_id [String, nil] Optional key identifier
+      # @return [ECDSA::Key] The loaded key
       def new_ecdsa_p384_sha384_key(material, key_id = nil)
         key = OpenSSL::PKey::EC.new(material)
         Linzer::ECDSA::Key.new(key, id: key_id, digest: "SHA384")
       end
 
+      # Generates a new JWS key for the specified algorithm.
+      #
+      # This method generates keys compatible with JSON Web Signature (JWS)
+      # format. Currently only EdDSA (Ed25519) is supported.
+      #
+      # @param algorithm [String] The JWS algorithm identifier (e.g., "EdDSA")
+      # @return [JWS::Key] A new JWS-compatible key
+      # @raise [Error] If the algorithm is not supported
+      #
+      # @example
+      #   key = Linzer.generate_jws_key(algorithm: "EdDSA")
       def generate_jws_key(algorithm:)
         Linzer::JWS.generate_key(algorithm: algorithm)
       end
 
+      # Imports a key from JWK (JSON Web Key) format.
+      #
+      # @param key [Hash] The JWK as a Hash (parsed from JSON)
+      # @param params [Hash] Additional key parameters
+      # @option params [String] :id Key identifier to use (overrides JWK "kid")
+      # @return [JWS::Key] The imported key
+      #
+      # @example Importing from JWK
+      #   jwk = JSON.parse(File.read("key.jwk"))
+      #   key = Linzer.jwk_import(jwk)
       def jwk_import(key, params = {})
         Linzer::JWS.jwk_import(key, params)
       end