linzer 0.7.7 → 0.7.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcae916cefddaddfc6fd6b58ab110eceda2225e5b525c984fa20eba378d80262
-  data.tar.gz: 896938aeafbca006f944a950bd0151df60f960ee7541ee98fe6aff2ffee9754f
+  metadata.gz: '002232186b5d47054f7f531537caf71c250774b56e09be381e967f770fdfec71'
+  data.tar.gz: 5c40887f1e5ba4e9695acecc011fc12c470268e35e8a4edc38076fb318d075f8
 SHA512:
-  metadata.gz: 89b1873e0664d7048142c9a16fd5414f3f568eeb01a3396d194398efa59e9e1bd40596096a433be17fa6635be9850cb641cd48b79d8ac99efe21d128c822337f
-  data.tar.gz: 61a79c4ef12ae7fbf74da3c0d99786caaa010255d099bb7c73319308a86895a4b5d531254f4bd3a7f78fb15aec1cc96f01bb02f83fa45313bae0c8910ca45b1b
+  metadata.gz: '08fc04ddd98910aadf1d7538ce29db51882960ee33a27e88030d29520bccac3f0cf06757560ef90de27849eaf8a3bfff7e713e478c5cf5d68bb975c38661c4e9'
+  data.tar.gz: 4b0a9b295522e9cf9736ad8db7b12ba9d010fc4c97f023f1cf0a6bf4ea7e8bea23430d1131af66dba04e6b195ee47ff45f4624618355c3553c7238e913fc4f70

data/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## [Unreleased]
 
+## [0.7.8] - 2026-03-03
+
+- Security fix: HMAC signature verification now uses constant-time
+  comparison to prevent timing attacks.
+
 ## [0.7.7] - 2025-07-08
 
 (No changes since the last beta release, this new stable release just

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2024-2025 Miguel Landaeta <miguel@miguel.cc>
+Copyright (c) 2024-2026 Miguel Landaeta <miguel@miguel.cc>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,4 +1,4 @@
-# Linzer [![Latest Version][gem-badge]][gem-link] [![License: MIT][license-image]][license-link] [![CI Status][ci-image]][ci-link]
+# Linzer [![Latest Version][gem-badge]][gem-link] [![License: MIT][license-image]][license-link] [![CI Status][ci-image]][ci-link] [![RubyDoc][rubydoc-badge]][rubydoc-link]
 
 [gem-badge]: https://badge.fury.io/rb/linzer.svg
 [gem-link]: https://rubygems.org/gems/linzer
@@ -6,6 +6,8 @@
 [license-link]: https://github.com/nomadium/linzer/blob/master/LICENSE.txt
 [ci-image]: https://github.com/nomadium/linzer/actions/workflows/main.yml/badge.svg?branch=master
 [ci-link]: https://github.com/nomadium/linzer/actions/workflows/main.yml
+[rubydoc-badge]: https://img.shields.io/badge/docs-RubyDoc.info-blue
+[rubydoc-link]: https://www.rubydoc.info/gems/linzer
 
 Linzer is a Ruby library for [HTTP Message Signatures (RFC 9421)](https://www.rfc-editor.org/rfc/rfc9421.html).
 

data/flake.lock

@@ -0,0 +1,109 @@
+{
+  "nodes": {
+    "bundix": {
+      "inputs": {
+        "nixpkgs": "nixpkgs"
+      },
+      "locked": {
+        "lastModified": 1762235257,
+        "narHash": "sha256-QyXFgaXQETr9BmwUbWM/2EtF+my6Arpt71xItZy3NL8=",
+        "owner": "inscapist",
+        "repo": "bundix",
+        "rev": "2233b24084316b4de1d55321483554f457a09cfc",
+        "type": "github"
+      },
+      "original": {
+        "owner": "inscapist",
+        "repo": "bundix",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1761880412,
+        "narHash": "sha256-QoJjGd4NstnyOG4mm4KXF+weBzA2AH/7gn1Pmpfcb0A=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "a7fc11be66bdfb5cdde611ee5ce381c183da8386",
+        "type": "github"
+      },
+      "original": {
+        "id": "nixpkgs",
+        "type": "indirect"
+      }
+    },
+    "nixpkgs_2": {
+      "locked": {
+        "lastModified": 1770115704,
+        "narHash": "sha256-KHFT9UWOF2yRPlAnSXQJh6uVcgNcWlFqqiAZ7OVlHNc=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "e6eae2ee2110f3d31110d5c222cd395303343b08",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs_3": {
+      "locked": {
+        "lastModified": 1678875422,
+        "narHash": "sha256-T3o6NcQPwXjxJMn2shz86Chch4ljXgZn746c2caGxd8=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "126f49a01de5b7e35a43fd43f891ecf6d3a51459",
+        "type": "github"
+      },
+      "original": {
+        "id": "nixpkgs",
+        "type": "indirect"
+      }
+    },
+    "root": {
+      "inputs": {
+        "bundix": "bundix",
+        "nixpkgs": "nixpkgs_2",
+        "ruby-nix": "ruby-nix",
+        "systems": "systems"
+      }
+    },
+    "ruby-nix": {
+      "inputs": {
+        "nixpkgs": "nixpkgs_3"
+      },
+      "locked": {
+        "lastModified": 1755059052,
+        "narHash": "sha256-yUJmmNIw11ZEIAFogqcqNomk4YV3F/zjwI1f7bYzIyY=",
+        "owner": "inscapist",
+        "repo": "ruby-nix",
+        "rev": "86b498e80058a84461d1f533e121574d85d272d7",
+        "type": "github"
+      },
+      "original": {
+        "owner": "inscapist",
+        "repo": "ruby-nix",
+        "type": "github"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1689347949,
+        "narHash": "sha256-12tWmuL2zgBgZkdoB6qXZsgJEH9LR3oUgpaQq2RbI80=",
+        "owner": "nix-systems",
+        "repo": "default-linux",
+        "rev": "31732fcf5e8fea42e59c2488ad31a0e651500f68",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default-linux",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

data/flake.nix

@@ -0,0 +1,73 @@
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    # XXX: should work, not tested yet on MacOS
+    # systems.url = "github:nix-systems/default";
+    systems.url = "github:nix-systems/default-linux";
+    ruby-nix.url = "github:inscapist/ruby-nix";
+    bundix.url = "github:inscapist/bundix";
+  };
+
+  outputs = {
+    self,
+    nixpkgs,
+    systems,
+    ruby-nix,
+    bundix,
+  }: let
+    eachSystem = f: nixpkgs.lib.genAttrs (import systems) (system: f system);
+
+    makeRubyEnv = system: let
+      pkgs = import nixpkgs {inherit system;};
+      rubyNix = ruby-nix.lib pkgs;
+      gemset = import ./gemset.nix;
+      rubyEnv = rubyNix {
+        name = "linzer-gems";
+        inherit gemset;
+        ruby = pkgs.ruby;
+        gemConfig = pkgs.defaultGemConfig;
+      };
+    in {
+      inherit pkgs rubyEnv;
+    };
+  in {
+    devShells = eachSystem (system: let
+      env = makeRubyEnv system;
+    in {
+      default = env.pkgs.mkShell {
+        packages = [
+          env.rubyEnv.ruby
+          env.rubyEnv.env
+        ];
+      };
+    });
+
+    checks = eachSystem (system: let
+      env = makeRubyEnv system;
+    in {
+      default = env.pkgs.stdenv.mkDerivation {
+        name = "linzer-unit-tests";
+        src = ./.;
+
+        nativeBuildInputs = [
+          env.rubyEnv.ruby
+          env.rubyEnv.env
+          env.pkgs.git
+        ];
+
+        doCheck = true;
+
+        checkPhase = ''
+          export HOME=$PWD/.nix-home
+          mkdir -p $HOME
+          rake
+        '';
+
+        installPhase = ''
+          mkdir -p $out
+          touch $out/done
+        '';
+      };
+    });
+  };
+}

data/lib/linzer/common.rb

@@ -1,7 +1,31 @@
 # frozen_string_literal: true
 
 module Linzer
+  # Shared functionality for signature base computation and validation.
+  #
+  # This module contains the core logic for building the canonical signature
+  # base string that gets signed/verified, as defined in RFC 9421 Section 2.5.
+  #
+  # @api private
+  # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-2.5 RFC 9421 Section 2.5
   module Common
+    # Computes the signature base string for an HTTP message.
+    #
+    # The signature base is a canonical string representation of the covered
+    # components, formatted according to RFC 9421. This is the string that
+    # gets cryptographically signed.
+    #
+    # @param message [Message] The HTTP message
+    # @param serialized_components [Array<String>] Serialized component identifiers
+    # @param parameters [Hash] Signature parameters (created, keyid, etc.)
+    # @return [String] The signature base string
+    #
+    # @example Signature base format
+    #   # Each covered component on its own line:
+    #   # "@method": POST
+    #   # "@path": /foo
+    #   # "content-type": application/json
+    #   # "@signature-params": ("@method" "@path" "content-type");created=1618884473
     def signature_base(message, serialized_components, parameters)
       signature_base =
         serialized_components.each_with_object(+"") do |component, base|
@@ -14,12 +38,25 @@ module Linzer
     end
     module_function :signature_base
 
+    # Builds a single line of the signature base for a component.
+    #
+    # @param component [String] The serialized component identifier
+    # @param message [Message] The HTTP message
+    # @return [String] The formatted line (e.g., '"@method": POST')
     def signature_base_line(component, message)
       field_id = FieldId.new(field_name: component)
       "%s: %s" % [field_id.serialize, message[field_id]]
     end
     module_function :signature_base_line
 
+    # Builds the @signature-params line for the signature base.
+    #
+    # This is always the last line of the signature base and contains
+    # the covered components list and signature parameters.
+    #
+    # @param serialized_components [Array<String>] The covered components
+    # @param parameters [Hash] Signature parameters
+    # @return [String] The formatted @signature-params line
     def signature_params_line(serialized_components, parameters)
       identifiers = serialized_components.map { |c| Starry.parse_item(c) }
 
@@ -32,6 +69,13 @@ module Linzer
 
     private
 
+    # Validates that all specified components are valid and present.
+    #
+    # @param message [Message] The HTTP message
+    # @param components [Array<String>] Component identifiers to validate
+    # @raise [Error] If @signature-params is in the components
+    # @raise [Error] If any component is missing from the message
+    # @raise [Error] If any component is duplicated
     def validate_components(message, components)
       if components.include?('"@signature-params"') ||
           components.any? { |c| c.start_with?('"@signature-params"') }
@@ -46,6 +90,13 @@ module Linzer
       validate_uniqueness components
     end
 
+    # Validates that there are no duplicate components.
+    #
+    # Components are considered duplicates if they have the same value
+    # and parameters, even if serialized differently.
+    #
+    # @param components [Array<String>] Component identifiers to check
+    # @raise [Error] If any component appears more than once
     def validate_uniqueness(components)
       msg = "Invalid signature. Duplicated component in signature input."
 

data/lib/linzer/ecdsa.rb

@@ -1,18 +1,61 @@
 # frozen_string_literal: true
 
 module Linzer
+  # ECDSA (Elliptic Curve Digital Signature Algorithm) support.
+  #
+  # Supports P-256 (secp256r1/prime256v1) and P-384 (secp384r1) curves
+  # with SHA-256 and SHA-384 digests respectively.
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-3.3.3 RFC 9421 Section 3.3.3
   module ECDSA
+    # ECDSA signing key implementation.
+    #
+    # ECDSA keys provide a good balance of security and performance.
+    # Supported algorithm identifiers:
+    # - `ecdsa-p256-sha256` - NIST P-256 curve with SHA-256
+    # - `ecdsa-p384-sha384` - NIST P-384 curve with SHA-384
+    #
+    # @note ECDSA signatures are converted between DER format (used by OpenSSL)
+    #   and the concatenated r||s format required by RFC 9421.
+    #
+    # @example Generating a P-256 key
+    #   key = Linzer.generate_ecdsa_p256_sha256_key("my-key")
+    #
+    # @example Loading from PEM
+    #   key = Linzer.new_ecdsa_p256_sha256_key(File.read("ec_key.pem"), "key-1")
+    #
+    # @see Linzer::Key::Helper#generate_ecdsa_p256_sha256_key
+    # @see Linzer::Key::Helper#generate_ecdsa_p384_sha384_key
     class Key < Linzer::Key
+      # @api private
       def validate
         super
         validate_digest
       end
 
+      # Signs data using the ECDSA private key.
+      #
+      # The signature is returned in concatenated r||s format as required
+      # by RFC 9421, not in DER format.
+      #
+      # @param data [String] The data to sign
+      # @return [String] The signature bytes (64 bytes for P-256, 96 for P-384)
+      # @raise [SigningError] If this key does not contain private key material
       def sign(data)
         validate_signing_key
         decode_der_signature(material.sign(@params[:digest], data))
       end
 
+      # Verifies a signature using the ECDSA public key.
+      #
+      # Expects the signature in concatenated r||s format as specified
+      # by RFC 9421.
+      #
+      # @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
+      # @raise [Error] If the signature format is invalid
       def verify(signature, data)
         validate_verify_key
         material.verify(@params[:digest], der_signature(signature), data)
@@ -20,12 +63,17 @@ module Linzer
 
       private
 
+      # Mapping of digest algorithms to signature format parameters.
+      # hex_length is the total length of r||s in hex characters.
       DIGEST_PARAMS = {
         "SHA256" => {hex_format: "%.64x", hex_length: 64},
         "SHA384" => {hex_format: "%.96x", hex_length: 96}
       }
       private_constant :DIGEST_PARAMS
 
+      # Converts concatenated r||s format to DER for OpenSSL verification.
+      # @param sig [String] Signature in r||s format
+      # @return [String] DER-encoded signature
       def der_signature(sig)
         digest = @params[:digest]
         msg = "Cannot verify invalid signature."
@@ -47,6 +95,9 @@ module Linzer
         seq.to_der
       end
 
+      # Converts DER-encoded signature to concatenated r||s format.
+      # @param der_sig [String] DER-encoded signature from OpenSSL
+      # @return [String] Signature in r||s format
       def decode_der_signature(der_sig)
         digest = @params[:digest]
         msg = "Unsupported digest algorithm: '%s'" % digest

data/lib/linzer/ed25519.rb

@@ -1,22 +1,57 @@
 # frozen_string_literal: true
 
 module Linzer
+  # Ed25519 elliptic curve signature algorithm support.
+  #
+  # Ed25519 is a modern, high-security signature algorithm that is fast
+  # and produces compact signatures. It's recommended for new applications
+  # where compatibility with older systems is not required.
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-3.3.6 RFC 9421 Section 3.3.6
+  # @see https://ed25519.cr.yp.to/ Ed25519 specification
   module Ed25519
+    # Ed25519 signing key implementation.
+    #
+    # Ed25519 keys can be used for both signing (with private key) and
+    # verification (with public key). The algorithm identifier is `ed25519`.
+    #
+    # @example Generating a new key pair
+    #   key = Linzer.generate_ed25519_key("my-key-id")
+    #
+    # @example Loading from PEM
+    #   private_key = Linzer.new_ed25519_key(File.read("ed25519.pem"), "key-1")
+    #   public_key = Linzer.new_ed25519_public_key(File.read("ed25519_pub.pem"), "key-1")
+    #
+    # @see Linzer::Key::Helper#generate_ed25519_key
+    # @see Linzer::Key::Helper#new_ed25519_key
     class Key < Linzer::Key
+      # Signs data using the Ed25519 private key.
+      #
+      # @param data [String] The data to sign (typically the signature base)
+      # @return [String] The 64-byte Ed25519 signature
+      # @raise [SigningError] If this key does not contain private key material
       def sign(data)
         validate_signing_key
         material.sign(nil, data)
       end
 
+      # Verifies a signature using the Ed25519 public key.
+      #
+      # @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(nil, signature, data)
       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

data/lib/linzer/helper.rb

@@ -1,7 +1,51 @@
 # frozen_string_literal: true
 
 module Linzer
+  # Convenience methods for signing and verifying HTTP messages.
+  #
+  # These methods provide a simpler interface for common use cases,
+  # handling message wrapping and signature attachment automatically.
+  #
+  # @note These methods are mixed into the {Linzer} module and can be
+  #   called directly as `Linzer.sign!` and `Linzer.verify!`.
   module Helper
+    # Signs an HTTP request or response and attaches the signature.
+    #
+    # This is a convenience method that wraps the message, creates a signature,
+    # and attaches it to the original HTTP message in one step.
+    #
+    # @param request_or_response [Net::HTTPRequest, Net::HTTPResponse, Rack::Request,
+    #   Rack::Response, HTTP::Request] The HTTP message to sign
+    # @param args [Hash] Keyword arguments
+    # @option args [Linzer::Key] :key The private key to sign with (required)
+    # @option args [Array<String>] :components The components to include in the
+    #   signature (required). Example: `%w[@method @path content-type]`
+    # @option args [String] :label Optional signature label (defaults to "sig1")
+    # @option args [Hash] :params Additional signature parameters (created, nonce, etc.)
+    #
+    # @return [Object] The original HTTP message with signature headers attached
+    #
+    # @raise [SigningError] If signing fails
+    # @raise [KeyError] If required arguments are missing
+    #
+    # @example Sign a Net::HTTP request
+    #   request = Net::HTTP::Post.new(uri)
+    #   request["content-type"] = "application/json"
+    #   request["date"] = Time.now.httpdate
+    #
+    #   Linzer.sign!(request,
+    #     key: private_key,
+    #     components: %w[@method @path content-type date]
+    #   )
+    #   # request now has "signature" and "signature-input" headers
+    #
+    # @example Sign with additional parameters
+    #   Linzer.sign!(request,
+    #     key: private_key,
+    #     components: %w[@method @path],
+    #     label: "my-sig",
+    #     params: { nonce: SecureRandom.hex(16), tag: "my-app" }
+    #   )
     def sign!(request_or_response, **args)
       message = Message.new(request_or_response)
       options = {}
@@ -15,6 +59,41 @@ module Linzer
       message.attach!(signature)
     end
 
+    # Verifies a signed HTTP request or response.
+    #
+    # Extracts the signature from the message headers, rebuilds the signature
+    # base, and verifies the cryptographic signature.
+    #
+    # @param request_or_response [Net::HTTPRequest, Net::HTTPResponse, Rack::Request,
+    #   Rack::Response, HTTP::Request, HTTP::Response] The signed HTTP message
+    # @param key [Linzer::Key, nil] The public key to verify with. If nil,
+    #   a block must be provided to look up the key.
+    # @param no_older_than [Integer] Maximum signature age in seconds.
+    #   Defaults to 900 (15 minutes). Set to nil to disable age checking.
+    #
+    # @yield [keyid] Block to look up the verification key by keyid.
+    #   Only called if `key` is nil.
+    # @yieldparam keyid [String] The key identifier from the signature
+    # @yieldreturn [Linzer::Key] The public key to use for verification
+    #
+    # @return [true] Returns true if verification succeeds
+    #
+    # @raise [VerifyError] If verification fails
+    # @raise [Error] If no key is provided and no keyid is in the signature
+    #
+    # @example Verify with a known key
+    #   Linzer.verify!(request, key: public_key)
+    #
+    # @example Verify with key lookup
+    #   Linzer.verify!(request) do |keyid|
+    #     PublicKey.find_by(identifier: keyid).to_linzer_key
+    #   end
+    #
+    # @example Verify with custom age limit (5 minutes)
+    #   Linzer.verify!(request, key: public_key, no_older_than: 300)
+    #
+    # @example Verify without age checking
+    #   Linzer.verify!(request, key: public_key, no_older_than: nil)
     def verify!(request_or_response, key: nil, no_older_than: 900)
       message = Message.new(request_or_response)
       signature_headers = {}

data/lib/linzer/hmac.rb

@@ -3,29 +3,75 @@
 require "digest"
 
 module Linzer
+  # HMAC (Hash-based Message Authentication Code) symmetric signing support.
+  #
+  # HMAC uses a shared secret key for both signing and verification.
+  # This is useful when both parties can securely share a secret.
+  #
+  # @note HMAC keys are symmetric - the same key is used for signing and
+  #   verification. Keep the key material secret!
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc9421.html#section-3.3.5 RFC 9421 Section 3.3.5
   module HMAC
+    # HMAC signing key implementation.
+    #
+    # HMAC-SHA256 is the primary supported algorithm, using the
+    # `hmac-sha256` algorithm identifier.
+    #
+    # @example Generating a new key
+    #   key = Linzer.generate_hmac_sha256_key("shared-key")
+    #
+    # @example Using existing secret material
+    #   secret = Base64.decode64(ENV["SIGNING_SECRET"])
+    #   key = Linzer.new_hmac_sha256_key(secret, "api-key")
+    #
+    # @see Linzer::Key::Helper#generate_hmac_sha256_key
+    # @see Linzer::Key::Helper#new_hmac_sha256_key
     class Key < Linzer::Key
+      # @api private
       def validate
         super
         validate_digest
       end
 
+      # Signs data using HMAC.
+      #
+      # @param data [String] The data to sign
+      # @return [String] The HMAC digest (32 bytes for SHA-256)
       def sign(data)
         OpenSSL::HMAC.digest(@params[:digest], material, data)
       end
 
+      # Verifies an HMAC signature using constant-time comparison.
+      #
+      # Uses OpenSSL.secure_compare to prevent timing attacks where an
+      # attacker could measure response times to guess valid signatures.
+      #
+      # @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
       def verify(signature, data)
-        signature == sign(data)
+        OpenSSL.secure_compare(signature, sign(data))
       end
 
+      # HMAC keys can always sign (they contain the secret).
+      # @return [Boolean] true if key material is present
       def private?
         !material.nil?
       end
 
+      # HMAC keys are symmetric, not public/private.
+      # @return [Boolean] always false for HMAC keys
       def public?
         false
       end
 
+      # Returns a safe string representation that doesn't leak the secret.
+      #
+      # The key material is intentionally excluded from the output to prevent
+      # accidental exposure in logs or error messages.
+      #
+      # @return [String] A string representation without the secret key
       def inspect
         vars =
           instance_variables

data/lib/linzer/http/bootstrap.rb

@@ -2,13 +2,24 @@
 
 module Linzer
   module HTTP
+    # Handles lazy loading of http.rb gem dependencies.
+    #
+    # The http.rb gem integration is optional and only loaded when
+    # explicitly required via `require "linzer/http/signature_feature"`.
+    #
+    # @api private
     module Bootstrap
       class << self
+        # Requires the http gem and related adapters.
+        # @api private
         def require_dependencies
           require "http"
           require_relative "../message/adapter/http_gem/request"
         end
 
+        # Loads dependencies, raising a helpful error if http gem is missing.
+        # @raise [Error] If the http gem is not installed
+        # @api private
         def load_dependencies
           require_dependencies
         rescue LoadError