http_message_signatures 0.1.0

data/lib/http_message_signatures/rfc9421/signature_base.rb

@@ -0,0 +1,61 @@
+module HTTPMessageSignatures
+  module RFC9421
+    # Constructs the signature base string per RFC 9421 Section 2.5.
+    #
+    # The signature base is an ASCII string containing the canonicalized HTTP
+    # message components covered by the signature, ending with the serialized
+    # @signature-params line.
+    #
+    # @example
+    #   base = SignatureBase.create(
+    #     signature_params: params,
+    #     method: "POST",
+    #     url: "https://example.com/foo",
+    #     headers: { "content-type" => "application/json" }
+    #   )
+    class SignatureBase
+      # Build the signature base string.
+      #
+      # @param signature_params [SignatureParams] The signature parameters
+      # @param headers [Hash{String => String}] HTTP headers
+      # @param method [String, nil] HTTP method
+      # @param status [Integer, nil] HTTP response status code
+      # @param url [String, URI, nil] Full request URL
+      # @return [String] The signature base string
+      # @raise [ParseError] If any component cannot be resolved
+      def self.create signature_params:, headers: {}, method: nil, status: nil, url: nil
+        resolver = ComponentResolver.new headers: headers, method: method, status: status, url: url
+
+        seen = {}
+        lines = []
+
+        signature_params.components.each do |component|
+          identifier = serialize_identifier component
+
+          raise ParseError, "Duplicate component identifier: #{identifier}" if seen[identifier]
+
+          seen[identifier] = true
+
+          value = resolver.resolve component
+          lines << "#{identifier}: #{value}"
+        end
+
+        lines << "\"@signature-params\": #{signature_params}"
+        lines.join "\n"
+      end
+
+      class << self
+        private
+
+        def serialize_identifier component
+          case component
+          when ComponentIdentifier
+            component.to_s
+          else
+            "\"#{component}\""
+          end
+        end
+      end
+    end
+  end
+end

data/lib/http_message_signatures/rfc9421/signature_params.rb

@@ -0,0 +1,117 @@
+require 'starry'
+
+module HTTPMessageSignatures
+  module RFC9421
+    # Represents RFC 9421 signature parameters: the covered components
+    # and metadata (created, expires, nonce, alg, keyid, tag).
+    #
+    # The serialized form is a Structured Fields Inner List with parameters,
+    # as defined in RFC 9421 Section 2.3.
+    #
+    # @example
+    #   params = SignatureParams.new(
+    #     components: ["@method", "@authority", "@path"],
+    #     created: 1618884473,
+    #     keyid: "test-key-rsa-pss"
+    #   )
+    #   params.to_s
+    #   # => '("@method" "@authority" "@path");created=1618884473;keyid="test-key-rsa-pss"'
+    class SignatureParams
+      METADATA_KEYS = %i[created expires nonce alg keyid tag].freeze
+
+      attr_reader :components
+      attr_accessor :created, :expires, :nonce, :alg, :keyid, :tag
+
+      def initialize components:, **metadata
+        @components = components
+        METADATA_KEYS.each { |key| instance_variable_set :"@#{key}", metadata[key] }
+      end
+
+      # Parse a Signature-Input member value (an Inner List with parameters).
+      #
+      # @param input [String] e.g. '("@method" "@authority");created=1618884473;keyid="test-key"'
+      # @return [SignatureParams]
+      # @raise [ParseError]
+      def self.parse input
+        list = Starry.parse_list input
+        inner_list = list.first
+
+        raise ParseError, "Expected inner list, got #{inner_list.class}" unless inner_list.is_a? Starry::InnerList
+
+        from_inner_list inner_list
+      rescue Starry::ParseError => e
+        raise ParseError, e.message
+      end
+
+      # Parse a full Signature-Input header (Dictionary of labeled inner lists).
+      #
+      # @param input [String] e.g. 'sig1=("@method");created=123, sig2=("@authority");created=456'
+      # @return [Hash{String => SignatureParams}]
+      # @raise [ParseError]
+      def self.parse_dictionary input
+        dict = Starry.parse_dictionary input
+        dict.transform_values { |inner_list| from_inner_list inner_list }
+      rescue Starry::ParseError => e
+        raise ParseError, e.message
+      end
+
+      # Serialize to the Signature-Input / @signature-params format.
+      #
+      # @return [String]
+      def to_s
+        to_inner_list.to_s
+      end
+
+      # Convert to a Starry::InnerList for use in dictionary serialization.
+      #
+      # @return [Starry::InnerList]
+      def to_inner_list
+        items = @components.map do |c|
+          case c
+          when ComponentIdentifier
+            Starry::Item.new c.name, c.params
+          else
+            c.to_s
+          end
+        end
+
+        params = {}
+        METADATA_KEYS.each do |key|
+          value = instance_variable_get :"@#{key}"
+          params[key.to_s] = value if value
+        end
+
+        Starry::InnerList.new items, params
+      end
+
+      class << self
+        private
+
+        def from_inner_list inner_list
+          raise ParseError, "Expected inner list, got #{inner_list.class}" unless inner_list.is_a? Starry::InnerList
+
+          components = inner_list.map { |item| item_to_component item }
+          metadata   = extract_metadata inner_list.parameters
+
+          new(components: components, **metadata)
+        end
+
+        def item_to_component item
+          return item.to_s unless item.is_a? Starry::Item
+          return item.value.to_s if item.parameters.empty?
+
+          ComponentIdentifier.new item.value.to_s, item.parameters
+        end
+
+        def extract_metadata parameters
+          metadata = {}
+          parameters.each do |key, value|
+            sym = key.to_sym
+            metadata[sym] = value if METADATA_KEYS.include? sym
+          end
+          metadata
+        end
+      end
+    end
+  end
+end

data/lib/http_message_signatures/rfc9421/signer.rb

@@ -0,0 +1,104 @@
+require 'base64'
+
+module HTTPMessageSignatures
+  module RFC9421
+    # Signs HTTP messages per RFC 9421.
+    #
+    # @example
+    #   signer = Signer.new(
+    #     key: private_key,
+    #     key_id: "my-key",
+    #     algorithm: "ed25519",
+    #     covered_components: %w[@method @authority @path content-type]
+    #   )
+    #   headers = signer.sign(
+    #     method: "POST",
+    #     url: "https://example.com/inbox",
+    #     headers: { "Content-Type" => "application/json" }
+    #   )
+    class Signer
+      # @param algorithm [String] Algorithm name (e.g. "ed25519", "rsa-pss-sha512")
+      # @param covered_components [Array<String, ComponentIdentifier>] Components to sign
+      # @param key [OpenSSL::PKey, String] Private key or shared secret
+      # @param key_id [String] Key identifier for the keyid parameter
+      # @param expires_in [Integer, nil] Seconds until expiration
+      # @param include_alg [Boolean] Include alg parameter (default: true)
+      # @param label [String] Signature label (default: "sig1")
+      # @param nonce [String, nil] Random nonce value
+      # @param tag [String, nil] Application-specific tag
+      def initialize algorithm:, covered_components:, key:, key_id:,
+                     expires_in: nil, include_alg: true, label: 'sig1', nonce: nil, tag: nil
+        @algorithm   = Algorithms.resolve algorithm
+        @alg_name    = algorithm
+        @components  = covered_components
+        @key         = key
+        @key_id      = key_id
+
+        @expires_in  = expires_in
+        @include_alg = include_alg
+        @label       = label
+        @nonce       = nonce
+        @tag         = tag
+      end
+
+      # Sign an HTTP request.
+      #
+      # @return [Hash{String => String}] Headers with Signature-Input and Signature added
+      def sign method:, url:, headers: {}
+        sign_message headers: headers, method: method, url: url
+      end
+
+      # Sign an HTTP response.
+      #
+      # @return [Hash{String => String}] Headers with Signature-Input and Signature added
+      def sign_response status:, headers: {}
+        sign_message headers: headers, status: status
+      end
+
+      private
+
+      def sign_message headers: {}, method: nil, status: nil, url: nil
+        params = build_params
+        base = build_base params, headers: headers, method: method, status: status, url: url
+
+        signature_bytes = @algorithm.sign @key, base
+        attach_headers headers, params, signature_bytes
+      end
+
+      def build_params
+        metadata = { created: Time.now.to_i, keyid: @key_id }
+        metadata[:alg] = @alg_name if @include_alg
+        metadata[:expires] = metadata[:created] + @expires_in if @expires_in
+        metadata[:nonce] = @nonce if @nonce
+        metadata[:tag] = @tag if @tag
+
+        SignatureParams.new components: @components, **metadata
+      end
+
+      def build_base params, headers: {}, method: nil, status: nil, url: nil
+        SignatureBase.create(
+          signature_params: params,
+          headers:          headers,
+          method:           method,
+          status:           status,
+          url:              url
+        )
+      end
+
+      def attach_headers headers, params, signature_bytes
+        encoded = Base64.strict_encode64 signature_bytes
+        new_input = "#{@label}=#{params}"
+        new_sig = "#{@label}=:#{encoded}:"
+
+        result = headers.dup
+        result['Signature-Input'] = append_dictionary_member result['Signature-Input'], new_input
+        result['Signature'] = append_dictionary_member result['Signature'], new_sig
+        result
+      end
+
+      def append_dictionary_member existing, new_member
+        existing ? "#{existing}, #{new_member}" : new_member
+      end
+    end
+  end
+end

data/lib/http_message_signatures/rfc9421/verifier.rb

@@ -0,0 +1,115 @@
+require 'base64'
+require 'starry'
+
+module HTTPMessageSignatures
+  module RFC9421
+    # Verifies HTTP message signatures per RFC 9421.
+    #
+    # @example
+    #   verifier = Verifier.new
+    #   result = verifier.verify(
+    #     method: "POST",
+    #     url: "https://example.com/inbox",
+    #     headers: headers
+    #   ) { |key_id, algorithm| fetch_key(key_id) }
+    class Verifier
+      # Verification result with structured data.
+      Result = Struct.new :verified, :label, :key_id, :algorithm, :components, keyword_init: true
+
+      # Verify a signed HTTP request.
+      #
+      # @yield [key_id, algorithm] Block to resolve the public key or shared secret
+      # @return [Result]
+      # @raise [ParseError] If headers are missing or malformed
+      def verify headers:, method:, url:, label: nil, &key_resolver
+        verify_message headers: headers, method: method, url: url, label: label, &key_resolver
+      end
+
+      # Verify a signed HTTP response.
+      #
+      # @yield [key_id, algorithm] Block to resolve the public key
+      # @return [Result]
+      def verify_response headers:, status:, label: nil, &key_resolver
+        verify_message headers: headers, status: status, label: label, &key_resolver
+      end
+
+      # List all signature labels present in the headers.
+      #
+      # @param headers [Hash{String => String}] HTTP headers
+      # @return [Array<String>] Signature labels
+      def labels headers
+        normalized = headers.transform_keys(&:downcase)
+        sig_input_raw = normalized['signature-input']
+        return [] unless sig_input_raw
+
+        SignatureParams.parse_dictionary(sig_input_raw).keys
+      end
+
+      # Verify all signatures on a request.
+      #
+      # @yield [key_id, algorithm] Block to resolve keys
+      # @return [Array<Result>]
+      def verify_all headers:, method:, url:, &key_resolver
+        labels(headers).map do |label|
+          verify headers: headers, method: method, url: url, label: label, &key_resolver
+        end
+      end
+
+      private
+
+      def verify_message headers: {}, label: nil, method: nil, status: nil, url: nil
+        params, signature_bytes, label = parse_signature_headers headers, label
+
+        key = yield params.keyid, params.alg
+        alg = Algorithms.resolve params.alg
+
+        base = SignatureBase.create(
+          signature_params: params,
+          headers:          headers,
+          method:           method,
+          status:           status,
+          url:              url
+        )
+
+        verified = alg.verify key, signature_bytes, base
+
+        Result.new verified: verified, label: label, key_id: params.keyid,
+                   algorithm: params.alg, components: params.components
+      end
+
+      def parse_signature_headers headers, label
+        normalized = headers.transform_keys(&:downcase)
+
+        sig_input_raw = normalized['signature-input']
+        sig_raw       = normalized['signature']
+        raise ParseError, 'Missing Signature-Input header' unless sig_input_raw
+        raise ParseError, 'Missing Signature header' unless sig_raw
+
+        sig_input_dict = SignatureParams.parse_dictionary sig_input_raw
+        sig_dict       = Starry.parse_dictionary sig_raw
+
+        label ||= sig_input_dict.keys.first
+        raise ParseError, "No signature found with label: #{label}" unless sig_input_dict.key? label
+
+        params = sig_input_dict[label]
+        signature_bytes = extract_signature_bytes sig_dict, sig_raw, label
+
+        [params, signature_bytes, label]
+      end
+
+      def extract_signature_bytes sig_dict, sig_raw, label
+        sig_entry = sig_dict[label]
+        raise ParseError, "No signature value for label: #{label}" unless sig_entry
+
+        sig_value = sig_entry.is_a?(Starry::Item) ? sig_entry.value : sig_entry
+        return sig_value if sig_value.is_a?(String) && sig_value.encoding == Encoding::ASCII_8BIT
+
+        # Fallback: manually extract base64 from the raw header
+        pattern = %r{#{Regexp.escape(label)}=:([A-Za-z0-9+/=]+):}
+        raise ParseError, "Cannot extract signature bytes for label: #{label}" unless sig_raw =~ pattern
+
+        Base64.strict_decode64 ::Regexp.last_match(1)
+      end
+    end
+  end
+end

data/lib/http_message_signatures/version.rb

@@ -0,0 +1,3 @@
+module HTTPMessageSignatures
+  VERSION = '0.1.0'.freeze
+end

data/lib/http_message_signatures.rb

@@ -0,0 +1,34 @@
+require 'starry'
+require 'strscan'
+
+require_relative 'http_message_signatures/version'
+require_relative 'http_message_signatures/errors'
+require_relative 'http_message_signatures/keys'
+require_relative 'http_message_signatures/cavage/signature_header'
+require_relative 'http_message_signatures/cavage/signing_string'
+require_relative 'http_message_signatures/cavage/signer'
+require_relative 'http_message_signatures/cavage/verifier'
+require_relative 'http_message_signatures/rfc9421/component_identifier'
+require_relative 'http_message_signatures/rfc9421/component_resolver'
+require_relative 'http_message_signatures/rfc9421/signature_params'
+require_relative 'http_message_signatures/rfc9421/signature_base'
+require_relative 'http_message_signatures/rfc9421/algorithms'
+require_relative 'http_message_signatures/rfc9421/signer'
+require_relative 'http_message_signatures/rfc9421/verifier'
+require_relative 'http_message_signatures/rack_middleware'
+require_relative 'http_message_signatures/http_signer'
+
+# HTTP Message Signatures for the Fediverse
+#
+# Sign and verify HTTP messages using draft-cavage (legacy Fediverse standard)
+# and RFC 9421 (the final HTTP Message Signatures standard).
+#
+# @example Signing a request (draft-cavage)
+#   signer = HTTPMessageSignatures::CavageSigner.new(key_id: 'https://example.com/actor#main-key', private_key: key)
+#   headers = signer.sign(method: 'POST', url: 'https://remote.example/inbox', headers: headers, body: body)
+#
+# @example Verifying a request (draft-cavage)
+#   verifier = HTTPMessageSignatures::CavageVerifier.new
+#   result = verifier.verify(method: 'POST', url: '/inbox', headers: headers, body: body) { |key_id| fetch_key(key_id) }
+module HTTPMessageSignatures
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: http_message_signatures
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shane Becker
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.3'
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: starry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+description: |
+  Sign and verify HTTP messages using draft-cavage (legacy Fediverse standard)
+  and RFC 9421 (the final HTTP Message Signatures standard).
+  Supports RSA-SHA256, RSA-PSS, HMAC-SHA256, ECDSA, and Ed25519.
+email:
+- veganstraightedge@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- lib/http_message_signatures.rb
+- lib/http_message_signatures/cavage/signature_header.rb
+- lib/http_message_signatures/cavage/signer.rb
+- lib/http_message_signatures/cavage/signing_string.rb
+- lib/http_message_signatures/cavage/verifier.rb
+- lib/http_message_signatures/errors.rb
+- lib/http_message_signatures/http_signer.rb
+- lib/http_message_signatures/keys.rb
+- lib/http_message_signatures/rack_middleware.rb
+- lib/http_message_signatures/rfc9421/algorithms.rb
+- lib/http_message_signatures/rfc9421/component_identifier.rb
+- lib/http_message_signatures/rfc9421/component_resolver.rb
+- lib/http_message_signatures/rfc9421/signature_base.rb
+- lib/http_message_signatures/rfc9421/signature_params.rb
+- lib/http_message_signatures/rfc9421/signer.rb
+- lib/http_message_signatures/rfc9421/verifier.rb
+- lib/http_message_signatures/version.rb
+homepage: https://github.com/xoengineering/http_message_signatures
+licenses:
+- AGPL-3.0
+metadata:
+  source_code_uri: https://github.com/xoengineering/http_message_signatures
+  changelog_uri: https://github.com/xoengineering/http_message_signatures/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 4.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: HTTP Message Signatures for the Fediverse
+test_files: []