http_message_signatures 0.1.0

data/lib/http_message_signatures/http_signer.rb

@@ -0,0 +1,108 @@
+require 'uri'
+
+module HTTPMessageSignatures
+  # Wraps the `http` gem client to automatically sign outgoing requests.
+  #
+  # Supports both draft-cavage and RFC 9421 signing.
+  #
+  # @example Draft-Cavage signing (Fediverse standard)
+  #   client = HTTPMessageSignatures::HTTPSigner.new(
+  #     key_id:      'https://example.com/users/alice#main-key',
+  #     private_key: private_key
+  #   )
+  #   response = client.post('https://remote.example/inbox',
+  #     headers: { 'Content-Type' => 'application/activity+json' },
+  #     body:    '{"type":"Follow"}'
+  #   )
+  #
+  # @example RFC 9421 signing
+  #   client = HTTPMessageSignatures::HTTPSigner.new(
+  #     key_id:      'my-key-id',
+  #     private_key: private_key,
+  #     mode:        :rfc9421,
+  #     algorithm:   'ed25519'
+  #   )
+  class HTTPSigner
+    # @param key_id [String] Key identifier
+    # @param private_key [OpenSSL::PKey] Private key for signing
+    # @param algorithm [String] Algorithm for RFC 9421 (default: 'rsa-v1_5-sha256')
+    # @param covered_components [Array<String>] Components for RFC 9421
+    # @param http [HTTP::Client, nil] Custom HTTP client (default: HTTP gem)
+    # @param mode [:cavage, :rfc9421] Signing mode (default: :cavage)
+    def initialize key_id:, private_key:,
+                   algorithm: 'rsa-v1_5-sha256', covered_components: nil,
+                   http: nil, mode: :cavage
+      @key_id      = key_id
+      @private_key = private_key
+      @mode        = mode
+      @algorithm   = algorithm
+      @components  = covered_components
+      @http        = http || default_http
+    end
+
+    %i[get head delete].each do |verb|
+      define_method verb do |url, headers: {}, body: nil|
+        request verb, url, headers: headers, body: body
+      end
+    end
+
+    %i[post put patch].each do |verb|
+      define_method verb do |url, headers: {}, body: nil|
+        request verb, url, headers: headers, body: body
+      end
+    end
+
+    private
+
+    def request verb, url, headers: {}, body: nil
+      signed = sign_headers verb, url, headers, body
+      @http.request verb, url, headers: signed, body: body
+    end
+
+    def sign_headers verb, url, headers, body
+      case @mode
+      when :cavage  then sign_cavage(verb, url, headers, body)
+      when :rfc9421 then sign_rfc9421(verb, url, headers, body)
+      else raise ArgumentError, "Unknown signing mode: #{@mode}"
+      end
+    end
+
+    def sign_cavage verb, url, headers, body
+      uri = URI.parse url.to_s
+      headers = ensure_host headers, uri
+
+      signer = Cavage::Signer.new key_id: @key_id, private_key: @private_key
+      signer.sign headers: headers, method: verb.to_s.upcase, path: uri.request_uri, body: body
+    end
+
+    def sign_rfc9421 verb, url, headers, body
+      uri = URI.parse url.to_s
+      headers = ensure_host headers, uri
+
+      components = @components || default_rfc9421_components(verb, body)
+
+      signer = RFC9421::Signer.new(
+        key:                @private_key,
+        key_id:             @key_id,
+        algorithm:          @algorithm,
+        covered_components: components
+      )
+      signer.sign method: verb.to_s.upcase, url: url.to_s, headers: headers
+    end
+
+    def ensure_host headers, uri
+      result = headers.dup
+      result['Host'] ||= uri.host
+      result
+    end
+
+    def default_rfc9421_components _verb, _body
+      %w[@method @authority @path content-type]
+    end
+
+    def default_http
+      require 'http'
+      HTTP
+    end
+  end
+end

data/lib/http_message_signatures/keys.rb

@@ -0,0 +1,58 @@
+require 'openssl'
+
+module HTTPMessageSignatures
+  # Key generation and PEM parsing helpers for HTTP Message Signatures.
+  #
+  # Supports RSA and Ed25519 — the two key types used in the Fediverse.
+  module Keys
+    module_function
+
+    # Generate an RSA key pair.
+    #
+    # @param bits [Integer] key size in bits (default: 2048)
+    # @return [OpenSSL::PKey::RSA] private key (call .public_key for the public half)
+    def generate_rsa bits: 2048
+      OpenSSL::PKey::RSA.generate bits
+    end
+
+    # Generate an Ed25519 key pair.
+    #
+    # @return [OpenSSL::PKey::PKey] private key
+    def generate_ed25519
+      OpenSSL::PKey.generate_key 'ED25519'
+    end
+
+    # Parse a PEM-encoded private key.
+    #
+    # @param pem [String] PEM string
+    # @return [OpenSSL::PKey::PKey]
+    def parse_private_key pem
+      OpenSSL::PKey.read pem
+    rescue OpenSSL::PKey::PKeyError => e
+      raise KeyError, "Cannot parse private key: #{e.message}"
+    end
+
+    # Parse a PEM-encoded public key.
+    #
+    # @param pem [String] PEM string
+    # @return [OpenSSL::PKey::PKey]
+    def parse_public_key pem
+      OpenSSL::PKey.read pem
+    rescue OpenSSL::PKey::PKeyError => e
+      raise KeyError, "Cannot parse public key: #{e.message}"
+    end
+
+    # Export a key to PEM format.
+    #
+    # @param key [OpenSSL::PKey::PKey] any OpenSSL key object
+    # @param private_key [Boolean] export private key (default: false, exports public)
+    # @return [String] PEM string
+    def to_pem key, private_key: false
+      if private_key
+        key.private_to_pem
+      else
+        key.public_to_pem
+      end
+    end
+  end
+end

data/lib/http_message_signatures/rack_middleware.rb

@@ -0,0 +1,141 @@
+require 'rack'
+
+module HTTPMessageSignatures
+  # Rack middleware that verifies HTTP message signatures on incoming requests.
+  #
+  # Supports both draft-cavage and RFC 9421 signatures. Detects which format
+  # is present based on the headers: RFC 9421 uses Signature-Input, while
+  # draft-cavage uses the Signature header alone.
+  #
+  # @example Basic usage in config.ru
+  #   use HTTPMessageSignatures::RackMiddleware do |key_id|
+  #     fetch_public_key(key_id)
+  #   end
+  #
+  # @example With options
+  #   use HTTPMessageSignatures::RackMiddleware,
+  #     paths:      ['/inbox'],
+  #     clock_skew: 300,
+  #     on_failure: ->(env, error) { [403, {}, ['Forbidden']] }
+  #   do |key_id|
+  #     fetch_public_key(key_id)
+  #   end
+  class RackMiddleware
+    DEFAULT_FAILURE_RESPONSE = [401, { 'content-type' => 'text/plain' }, ['Unauthorized']].freeze
+
+    # @param app [#call] The next Rack app
+    # @param clock_skew [Integer, nil] Clock skew for Cavage Date validation (default: 12h)
+    # @param on_failure [Proc, nil] Custom failure handler, receives (env, error) and returns Rack response
+    # @param paths [Array<String>, nil] Only verify requests matching these path prefixes (nil = all)
+    # @yield [key_id] Block to resolve a key_id to an OpenSSL public key
+    def initialize app, clock_skew: Cavage::Verifier::DEFAULT_CLOCK_SKEW, on_failure: nil, paths: nil, &key_resolver
+      @app          = app
+      @paths        = paths
+      @key_resolver = key_resolver
+      @on_failure   = on_failure
+      @cavage       = Cavage::Verifier.new clock_skew: clock_skew
+      @rfc9421      = RFC9421::Verifier.new
+    end
+
+    def call env
+      return @app.call(env) unless verify_path?(env)
+
+      headers = extract_headers env
+      return @app.call(env) unless signed_request?(headers)
+
+      body = read_body env
+      verify_request env, headers, body
+    rescue ParseError, VerificationError, KeyError => e
+      failure_response env, e
+    end
+
+    private
+
+    def verify_path? env
+      return true unless @paths
+
+      path = env['PATH_INFO']
+      @paths.any? { |prefix| path.start_with? prefix }
+    end
+
+    def signed_request? headers
+      headers.key?('Signature') || headers.key?('Signature-Input')
+    end
+
+    def extract_headers env
+      headers = {}
+      env.each do |key, value|
+        next unless key.start_with? 'HTTP_'
+
+        header_name = key[5..].tr('_', '-').split('-').map(&:capitalize).join('-')
+        headers[header_name] = value
+      end
+      headers['Host'] = env['HTTP_HOST'] || env['SERVER_NAME']
+      headers
+    end
+
+    def read_body env
+      input = env['rack.input']
+      return nil unless input
+
+      body = input.read
+      input.rewind
+      body
+    end
+
+    def verify_request env, headers, body
+      if headers.key? 'Signature-Input'
+        verify_rfc9421 env, headers
+      else
+        verify_cavage env, headers, body
+      end
+    end
+
+    def verify_cavage env, headers, body
+      method = env['REQUEST_METHOD']
+      path   = build_path env
+
+      verified = @cavage.verify(headers: headers, method: method, path: path, body: body, &@key_resolver)
+
+      return failure_response(env, VerificationError.new('Invalid signature')) unless verified
+
+      env['http_signature.verified'] = true
+      @app.call env
+    end
+
+    def verify_rfc9421 env, headers
+      method = env['REQUEST_METHOD']
+      url    = build_url env
+
+      result = @rfc9421.verify(headers: headers, method: method, url: url) do |key_id, _alg|
+        @key_resolver.call key_id
+      end
+
+      return failure_response(env, VerificationError.new('Invalid signature')) unless result.verified
+
+      env['http_signature.verified'] = true
+      env['http_signature.key_id']   = result.key_id
+      env['http_signature.algorithm'] = result.algorithm
+      @app.call env
+    end
+
+    def build_path env
+      path = env['PATH_INFO']
+      query = env['QUERY_STRING']
+      query && !query.empty? ? "#{path}?#{query}" : path
+    end
+
+    def build_url env
+      scheme = env['rack.url_scheme'] || 'https'
+      host   = env['HTTP_HOST'] || env['SERVER_NAME']
+      path   = build_path env
+      "#{scheme}://#{host}#{path}"
+    end
+
+    def failure_response env, error
+      return @on_failure.call(env, error) if @on_failure
+
+      DEFAULT_FAILURE_RESPONSE
+    end
+  end
+end

data/lib/http_message_signatures/rfc9421/algorithms.rb

@@ -0,0 +1,155 @@
+require 'openssl'
+
+module HTTPMessageSignatures
+  module RFC9421
+    # Algorithm implementations for RFC 9421 Section 3.3.
+    module Algorithms
+      # RSA-PSS using SHA-512 (Section 3.3.1)
+      module RsaPssSha512
+        ALG_NAME = 'rsa-pss-sha512'.freeze
+        PADDING_OPTS = {
+          'rsa_padding_mode' => 'pss',
+          'rsa_pss_saltlen'  => '64',
+          'rsa_mgf1_md'      => 'SHA512'
+        }.freeze
+
+        module_function
+
+        def sign private_key, data
+          private_key.sign 'SHA512', data, PADDING_OPTS
+        end
+
+        def verify public_key, signature, data
+          public_key.verify 'SHA512', signature, data, PADDING_OPTS
+        rescue OpenSSL::PKey::PKeyError
+          false
+        end
+      end
+
+      # RSASSA-PKCS1-v1_5 using SHA-256 (Section 3.3.2)
+      module RsaV15Sha256
+        ALG_NAME = 'rsa-v1_5-sha256'.freeze
+
+        module_function
+
+        def sign private_key, data
+          private_key.sign 'SHA256', data
+        end
+
+        def verify public_key, signature, data
+          public_key.verify 'SHA256', signature, data
+        rescue OpenSSL::PKey::PKeyError
+          false
+        end
+      end
+
+      # HMAC using SHA-256 (Section 3.3.3)
+      module HmacSha256
+        ALG_NAME = 'hmac-sha256'.freeze
+
+        module_function
+
+        def sign key, data
+          OpenSSL::HMAC.digest 'SHA256', key, data
+        end
+
+        def verify key, signature, data
+          expected = sign key, data
+          OpenSSL.fixed_length_secure_compare signature, expected
+        rescue ArgumentError
+          false
+        end
+      end
+
+      # ECDSA using curve P-256 and SHA-256 (Section 3.3.4)
+      # Signatures are raw r||s (64 bytes), not DER-encoded.
+      module EcdsaP256Sha256
+        ALG_NAME = 'ecdsa-p256-sha256'.freeze
+        COORD_SIZE = 32
+
+        module_function
+
+        def sign private_key, data
+          der_sig = private_key.sign 'SHA256', data
+          der_to_raw der_sig, COORD_SIZE
+        end
+
+        def verify public_key, signature, data
+          der_sig = raw_to_der signature, COORD_SIZE
+          public_key.verify 'SHA256', der_sig, data
+        rescue OpenSSL::PKey::PKeyError, OpenSSL::ASN1::ASN1Error
+          false
+        end
+
+        def der_to_raw der_sig, coord_size
+          asn1 = OpenSSL::ASN1.decode der_sig
+          r = asn1.value[0].value
+          s = asn1.value[1].value
+          r.to_s(2).rjust(coord_size, "\x00") + s.to_s(2).rjust(coord_size, "\x00")
+        end
+
+        def raw_to_der raw_sig, coord_size
+          r_bytes = raw_sig[0, coord_size]
+          s_bytes = raw_sig[coord_size, coord_size]
+          r = OpenSSL::BN.new r_bytes, 2
+          s = OpenSSL::BN.new s_bytes, 2
+          OpenSSL::ASN1::Sequence.new([
+                                        OpenSSL::ASN1::Integer.new(r),
+                                        OpenSSL::ASN1::Integer.new(s)
+                                      ]).to_der
+        end
+      end
+
+      # ECDSA using curve P-384 and SHA-384 (Section 3.3.5)
+      # Signatures are raw r||s (96 bytes), not DER-encoded.
+      module EcdsaP384Sha384
+        ALG_NAME = 'ecdsa-p384-sha384'.freeze
+        COORD_SIZE = 48
+
+        module_function
+
+        def sign private_key, data
+          der_sig = private_key.sign 'SHA384', data
+          EcdsaP256Sha256.der_to_raw der_sig, COORD_SIZE
+        end
+
+        def verify public_key, signature, data
+          der_sig = EcdsaP256Sha256.raw_to_der signature, COORD_SIZE
+          public_key.verify 'SHA384', der_sig, data
+        rescue OpenSSL::PKey::PKeyError, OpenSSL::ASN1::ASN1Error
+          false
+        end
+      end
+
+      # Ed25519 (Section 3.3.6)
+      module Ed25519
+        ALG_NAME = 'ed25519'.freeze
+
+        module_function
+
+        def sign private_key, data
+          private_key.sign nil, data
+        end
+
+        def verify public_key, signature, data
+          public_key.verify nil, signature, data
+        rescue OpenSSL::PKey::PKeyError
+          false
+        end
+      end
+
+      REGISTRY = {
+        'rsa-pss-sha512'    => RsaPssSha512,
+        'rsa-v1_5-sha256'   => RsaV15Sha256,
+        'hmac-sha256'       => HmacSha256,
+        'ecdsa-p256-sha256' => EcdsaP256Sha256,
+        'ecdsa-p384-sha384' => EcdsaP384Sha384,
+        'ed25519'           => Ed25519
+      }.freeze
+
+      def self.resolve name
+        REGISTRY[name] || raise(ParseError, "Unknown algorithm: #{name}")
+      end
+    end
+  end
+end

data/lib/http_message_signatures/rfc9421/component_identifier.rb

@@ -0,0 +1,61 @@
+module HTTPMessageSignatures
+  module RFC9421
+    # Represents a component identifier with optional parameters.
+    #
+    # A component identifier names a message component (e.g. "@method", "content-type")
+    # and may include parameters (e.g. "@query-param";name="Pet").
+    #
+    # @example Simple identifier
+    #   ComponentIdentifier.new("@method")
+    #
+    # @example With parameters
+    #   ComponentIdentifier.new("@query-param", "name" => "Pet")
+    class ComponentIdentifier
+      attr_reader :name, :params
+
+      def initialize name, params = {}
+        @name   = name
+        @params = params
+      end
+
+      # Is this a derived component (starts with @)?
+      def derived?
+        @name.start_with? '@'
+      end
+
+      # Serialize as an sf-string with parameters.
+      #
+      # @return [String] e.g. '"@query-param";name="Pet"'
+      def to_s
+        result = "\"#{@name}\""
+        @params.each do |key, value|
+          result += if value == true
+                      ";#{key}"
+                    else
+                      ";#{key}=\"#{value}\""
+                    end
+        end
+        result
+      end
+
+      def == other
+        case other
+        when String
+          @params.empty? && @name == other
+        when ComponentIdentifier
+          @name == other.name && @params == other.params
+        else
+          false
+        end
+      end
+
+      def eql? other
+        self == other
+      end
+
+      def hash
+        [@name, @params].hash
+      end
+    end
+  end
+end

data/lib/http_message_signatures/rfc9421/component_resolver.rb

@@ -0,0 +1,148 @@
+require 'uri'
+
+module HTTPMessageSignatures
+  module RFC9421
+    # Resolves HTTP message component values per RFC 9421 Section 2.
+    #
+    # Given a component identifier and a message context (method, URL, headers,
+    # status), returns the canonicalized component value.
+    class ComponentResolver
+      # @param headers [Hash{String => String}] HTTP headers (lowercase keys)
+      # @param method [String, nil] HTTP method (e.g. "POST")
+      # @param status [Integer, nil] HTTP response status code
+      # @param url [String, URI] Full request URL (e.g. "https://example.com/path?q=1")
+      def initialize headers: {}, method: nil, status: nil, url: nil
+        @method  = method
+        @uri     = url ? URI.parse(url.to_s) : nil
+        @headers = normalize_headers headers
+        @status  = status
+      end
+
+      # Resolve the value for a component identifier.
+      #
+      # @param component [String, ComponentIdentifier] Component name or identifier
+      # @return [String] Canonicalized component value
+      # @raise [ParseError] If the component cannot be resolved
+      DERIVED_RESOLVERS = {
+        '@method'         => :resolve_method,
+        '@target-uri'     => :resolve_target_uri,
+        '@authority'      => :resolve_authority,
+        '@scheme'         => :resolve_scheme,
+        '@request-target' => :resolve_request_target,
+        '@path'           => :resolve_path,
+        '@query'          => :resolve_query,
+        '@query-param'    => :resolve_query_param,
+        '@status'         => :resolve_status
+      }.freeze
+
+      # Resolve the value for a component identifier.
+      #
+      # @param component [String, ComponentIdentifier] Component name or identifier
+      # @return [String] Canonicalized component value
+      # @raise [ParseError] If the component cannot be resolved
+      def resolve component
+        name   = component.is_a?(ComponentIdentifier) ? component.name : component.to_s
+        params = component.is_a?(ComponentIdentifier) ? component.params : {}
+
+        if name.start_with? '@'
+          resolve_derived name, params
+        else
+          resolve_field name
+        end
+      end
+
+      private
+
+      def normalize_headers headers
+        headers.transform_keys(&:downcase)
+      end
+
+      def resolve_derived name, params
+        resolver = DERIVED_RESOLVERS[name]
+        raise ParseError, "Unknown derived component: #{name}" unless resolver
+
+        method(resolver).arity.zero? ? send(resolver) : send(resolver, params)
+      end
+
+      def resolve_method
+        raise ParseError, '@method requires a request message' unless @method
+
+        @method.to_s
+      end
+
+      def resolve_target_uri
+        raise ParseError, '@target-uri requires a request URL' unless @uri
+
+        @uri.to_s
+      end
+
+      def resolve_authority
+        raise ParseError, '@authority requires a request URL' unless @uri
+
+        authority = @uri.host.downcase
+        default_port = @uri.scheme == 'https' ? 443 : 80
+        authority = "#{authority}:#{@uri.port}" if @uri.port && @uri.port != default_port
+        authority
+      end
+
+      def resolve_scheme
+        raise ParseError, '@scheme requires a request URL' unless @uri
+
+        @uri.scheme.downcase
+      end
+
+      def resolve_request_target
+        raise ParseError, '@request-target requires a request URL' unless @uri
+
+        target = @uri.path.empty? ? '/' : @uri.path
+        target = "#{target}?#{@uri.query}" if @uri.query
+        target
+      end
+
+      def resolve_path
+        raise ParseError, '@path requires a request URL' unless @uri
+
+        @uri.path.empty? ? '/' : @uri.path
+      end
+
+      def resolve_query
+        raise ParseError, '@query requires a request URL' unless @uri
+
+        "?#{@uri.query || ''}"
+      end
+
+      def resolve_query_param params
+        raise ParseError, '@query-param requires a request URL' unless @uri
+        raise ParseError, '@query-param requires a name parameter' unless params['name']
+
+        target_name = params['name']
+        query_string = @uri.query || ''
+
+        # Parse query params per application/x-www-form-urlencoded
+        pairs = URI.decode_www_form query_string
+
+        match = pairs.find { |name, _value| name == target_name }
+        raise ParseError, "Query parameter not found: #{target_name}" unless match
+
+        # Re-encode the value per the RFC
+        URI.encode_www_form_component match[1]
+      end
+
+      def resolve_status
+        raise ParseError, '@status requires a response message' unless @status
+
+        @status.to_s
+      end
+
+      def resolve_field name
+        field_name = name.downcase
+        value = @headers[field_name]
+
+        raise ParseError, "Header field not found: #{name}" unless value
+
+        # Canonicalize: strip leading/trailing whitespace, collapse internal whitespace
+        value.strip.gsub(/\s+/, ' ')
+      end
+    end
+  end
+end