simple_oauth 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73fa4671190dbbe2dc7178055d4ef82aeaabf7044b384d198ee12a0fa48f6de5
-  data.tar.gz: f550391eb54731d6593dcab35f19bc419cbcbe63a6e48036be5f3cf4a419d069
+  metadata.gz: 7eca3b8d3940706967367e25b8f42261d48b325c8f2cd1c1cc01ad58a800f284
+  data.tar.gz: 63cec8ec4204dd64c40fdf61ecf1782df0364687794896199ded8a6dcb890ca3
 SHA512:
-  metadata.gz: 58f2b94d0568c491e46450e0c5cd35a9e45bed5827ee854fe17e02f4d02d74c3f5dd300eeebbfc890964afb72000a6e0f3b6db38db6599f063d3385b9dbe54c3
-  data.tar.gz: be077693f5d1c95b30f748f1915376862b540c419558dc6376d39c99c5991e1380f172c79e37a396f9e1450af6f22e48cec1c843b2c3afce3488731ba69401fe
+  metadata.gz: 967d4c8e1f174da75c8818fa0b94432ca2878d44474e5433930aa5bca728d4636b1ae4594e930be98fc68d6d9d57a40622dd5075ff507242100f424b95213e75
+  data.tar.gz: 7b24159117153d934834c2767692be078a78c58ec6fc34775d91bd90794767bbf86cbde9fb6306bcf5640b2a7b212f8bd0866e980ed3a871a3e0212120a7494b

data/CHANGELOG.md

@@ -1,3 +1,33 @@
+## [0.5.0] - 2026-09-12
+
+### Added
+
+* `Header.from_request`, which builds a header for a request object such as a `Net::HTTPRequest`, signing its query parameters, its form-encoded body, or hashing any other body
+* `Header.parse_query`, for OAuth credentials sent in a query string
+* `Signature.digest`, and a `digest:` option on `Signature.register`, which gives the hash algorithm a signature method signs with
+* `Signature.verify` and a `verify:` option on `Signature.register`, for signature methods that cannot be verified by recomputing the signature
+* `Signature.decode_base64`
+
+### Fixed
+
+* Check `oauth_body_hash` against the body a header was built with when verifying, so a body changed after signing no longer verifies against the hash its signature covers
+* Verify signatures without merging the given secrets into the header's own options, where anything else reading the header could see them
+* Compare signatures in constant time when verifying
+* Compute `oauth_body_hash` with the hash algorithm of the signature method, such as SHA-256 for HMAC-SHA256; it was always SHA-1
+* Sign a parameter whose value is an Array as one parameter per value, as a repeated parameter; the Array was previously signed as its Ruby representation
+* Verify RSA signatures with the signer's public key, which is all a verifier has; `Header#valid?` previously recomputed the signature and so needed the private key
+* Match the form-encoded media type exactly when signing a body, rather than by prefix, so a media type such as `application/x-www-form-urlencoded-json` is hashed instead of signed as parameters, and `Application/X-WWW-Form-Urlencoded` is recognized
+
+## [0.4.2] - 2026-09-12
+
+### Added
+
+* Document passing `Header` parameters as an Array of key-value pairs when a key repeats
+
+### Fixed
+
+* Accept an Array of key-value pairs as `Header` parameters in the RBS signatures, which already worked at runtime
+
 ## [0.4.1] - 2026-04-20
 
 ### Fixed

data/README.md

@@ -40,6 +40,35 @@ header.to_s
 # => "OAuth oauth_consumer_key=\"consumer_key\", oauth_nonce=\"...\", ..."
 ```
 
+### Signing a Request
+
+`Header.from_request` takes the method, URL, and parameters from a request object, such as a `Net::HTTPRequest`. Query parameters are always signed, a form-encoded body is signed as parameters, and any other body is hashed into `oauth_body_hash`:
+
+```ruby
+request = Net::HTTP::Post.new(URI("https://api.example.com/statuses"))
+request.set_form_data(status: "Hello")
+request["Authorization"] = SimpleOAuth::Header.from_request(request,
+  consumer_key: "key",
+  consumer_secret: "secret"
+).to_s
+```
+
+### Repeated Parameters
+
+Pass an Array of values, or an Array of key-value pairs, when a key repeats:
+
+```ruby
+header = SimpleOAuth::Header.new(:post, url, {"ids" => %w[1 2]},
+  consumer_key: "key",
+  consumer_secret: "secret"
+)
+
+header = SimpleOAuth::Header.new(:post, url, [["ids", "1"], ["ids", "2"]],
+  consumer_key: "key",
+  consumer_secret: "secret"
+)
+```
+
 ### Signature Methods
 
 Built-in signature methods: `HMAC-SHA1` (default), `HMAC-SHA256`, `RSA-SHA1`, `RSA-SHA256`, and `PLAINTEXT`.
@@ -76,7 +105,7 @@ SimpleOAuth::Signature.methods # => ["hmac_sha1", "hmac_sha256", "rsa_sha1", "rs
 
 ### OAuth Request Body Hash
 
-For non-form-encoded request bodies (e.g., JSON), pass the body as the fifth parameter to compute `oauth_body_hash`:
+For non-form-encoded request bodies (e.g., JSON), pass the body as the fifth parameter to compute `oauth_body_hash`, which is hashed with the signature method's algorithm. Form-encoded bodies are signed by passing their parameters as `params` instead.
 
 ```ruby
 json_body = '{"text": "Hello, World!"}'
@@ -109,11 +138,14 @@ parsed = SimpleOAuth::Header.parse('OAuth oauth_consumer_key="key", oauth_signat
 # => {consumer_key: "key", signature: "sig"}
 ```
 
-Parse OAuth credentials from a form-encoded POST body:
+Parse OAuth credentials from a form-encoded POST body, or from a query string:
 
 ```ruby
 parsed = SimpleOAuth::Header.parse_form_body('oauth_consumer_key=key&oauth_signature=sig&status=hello')
 # => {consumer_key: "key", signature: "sig"}
+
+parsed = SimpleOAuth::Header.parse_query("oauth_consumer_key=key&status=hello")
+# => {consumer_key: "key"}
 ```
 
 ### Verifying Signatures
@@ -127,6 +159,25 @@ header.valid?(consumer_secret: "secret", token_secret: "token_secret")
 # => true
 ```
 
+Verifying compares signatures in constant time and leaves the header's own options untouched, so the secrets stay with the caller.
+
+RSA signatures verify with the client's public key, which is all a server has:
+
+```ruby
+header.valid?(consumer_secret: File.read("client_public_key.pem"))
+```
+
+Custom signature methods that cannot be verified by recomputing the signature register a `verify` block:
+
+```ruby
+SimpleOAuth::Signature.register("RSA-SHA512", rsa: true,
+  verify: ->(key, signature_base, signature) {
+    OpenSSL::PKey::RSA.new(key).verify("SHA512", SimpleOAuth::Signature.decode_base64(signature), signature_base)
+  }) do |private_key_pem, signature_base|
+  SimpleOAuth::Signature.encode_base64(OpenSSL::PKey::RSA.new(private_key_pem).sign("SHA512", signature_base))
+end
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/laserlemon/simple_oauth.

data/lib/simple_oauth/header/class_methods.rb

@@ -13,17 +13,18 @@ module SimpleOAuth
       #
       # @api public
       # @param body [String, nil] optional request body for computing oauth_body_hash
+      # @param signature_method [String] the signature method, whose hash algorithm oauth_body_hash uses
       # @return [Hash] default options including nonce, signature_method, timestamp, and version
       # @example
       #   SimpleOAuth::Header.default_options
       #   # => {nonce: "abc123...", signature_method: "HMAC-SHA1", timestamp: "1234567890", version: "1.0"}
-      def default_options(body = nil)
+      def default_options(body = nil, signature_method = DEFAULT_SIGNATURE_METHOD)
         {
           nonce: generate_nonce,
-          signature_method: DEFAULT_SIGNATURE_METHOD,
+          signature_method: signature_method,
           timestamp: Integer(Time.now).to_s,
           version: OAUTH_VERSION
-        }.tap { |opts| opts[:body_hash] = body_hash(body) if body }
+        }.tap { |opts| opts[:body_hash] = body_hash(body, Signature.digest(signature_method)) if body }
       end
 
       # Computes the oauth_body_hash for a request body
@@ -52,6 +53,30 @@ module SimpleOAuth
         Parser.new(header).parse(PARSE_KEYS)
       end
 
+      # Builds a header for an HTTP request, signing the parameters it carries
+      #
+      # The request's query parameters are always signed. A form-encoded body is signed as
+      # parameters, and any other body is hashed into oauth_body_hash.
+      #
+      # @api public
+      # @param request [#method, #uri, #body] the request to sign, such as a Net::HTTPRequest
+      # @param oauth [Hash, String] OAuth options hash or an existing Authorization header to parse
+      # @return [Header] the header for the request
+      # @raise [ArgumentError] if the request has no URI
+      # @example
+      #   request = Net::HTTP::Post.new(URI("https://api.example.com/statuses"))
+      #   request.set_form_data(status: "Hello")
+      #   request["Authorization"] = SimpleOAuth::Header.from_request(request,
+      #     consumer_key: "key", consumer_secret: "secret").to_s
+      def from_request(request, oauth = {})
+        uri = request.uri || raise(ArgumentError, "The request has no URI")
+        body = request.body
+        return new(request.method, uri, CGI.parse(body.to_s), oauth) if form_encoded?(request)
+
+        no_params = {} #: Header::request_params
+        new(request.method, uri, no_params, oauth, body)
+      end
+
       # Parses OAuth parameters from a form-encoded POST body
       #
       # OAuth 1.0 allows credentials to be transmitted in the request body for
@@ -63,6 +88,9 @@ module SimpleOAuth
       # @example
       #   SimpleOAuth::Header.parse_form_body('oauth_consumer_key=key&oauth_signature=sig&status=hello')
       #   # => {consumer_key: "key", signature: "sig"}
+      # @example Parse the credentials from a query string
+      #   SimpleOAuth::Header.parse_query('oauth_consumer_key=key&status=hello')
+      #   # => {consumer_key: "key"}
       def parse_form_body(body)
         valid_keys = PARSE_KEYS.map(&:to_s)
 
@@ -76,8 +104,40 @@ module SimpleOAuth
         result
       end
 
+      # @!method parse_query(query)
+      #   Parses OAuth parameters from a query string, which RFC 5849 Section 3.5.3 also allows
+      #
+      #   @api public
+      #   @param query [String, #to_s] the query string
+      #   @return [Hash] parsed OAuth attributes with symbol keys (only valid OAuth keys)
+      #   @example
+      #     SimpleOAuth::Header.parse_query("oauth_consumer_key=key&status=hello")
+      #     # => {consumer_key: "key"}
+      alias_method :parse_query, :parse_form_body
+
       private
 
+      # Checks whether a request carries a form-encoded body
+      #
+      # @api private
+      # @param request [#[]] the request
+      # @return [Boolean] true if the body is form-encoded
+      def form_encoded?(request)
+        media_type(request).eql?(FORM_CONTENT_TYPE)
+      end
+
+      # Extracts the media type from a request, without its parameters
+      #
+      # Per RFC 9110 Section 8.3 the media type is case-insensitive and may carry parameters,
+      # such as a charset, that play no part in identifying it.
+      #
+      # @api private
+      # @param request [#[]] the request
+      # @return [String] the lowercase media type, or an empty String when the request declares none
+      def media_type(request)
+        request["Content-Type"].to_s.split(";").first.to_s.strip.downcase
+      end
+
       # Generates a random nonce for OAuth requests
       #
       # @api private

data/lib/simple_oauth/header/params.rb

@@ -0,0 +1,75 @@
+require "cgi"
+
+module SimpleOAuth
+  class Header
+    # Normalization of the request parameters that are signed, per RFC 5849 Section 3.4.1.3
+    #
+    # @api private
+    module Params
+      private
+
+      # Extracts valid OAuth attributes from options
+      #
+      # @api private
+      # @return [Hash] OAuth attributes without signature or realm
+      def attributes
+        validate_option_keys!
+        options.slice(*ATTRIBUTE_KEYS).transform_keys { |key| :"#{OAUTH_PREFIX}#{key}" }
+      end
+
+      # Validates that no unknown keys are present in options
+      #
+      # @api private
+      # @raise [InvalidOptionsError] if extra keys are found
+      # @return [void]
+      def validate_option_keys!
+        return if options[:ignore_extra_keys]
+
+        extra_keys = options.keys - ATTRIBUTE_KEYS - IGNORED_KEYS
+        return if extra_keys.empty?
+
+        raise InvalidOptionsError, "Unknown option keys: #{extra_keys.map(&:inspect).join(", ")}"
+      end
+
+      # Extracts query parameters from the request URL
+      #
+      # @api private
+      # @return [Array<Array>] URL query parameters as key-value pairs
+      def url_params
+        CGI.parse(@uri.query || "").flat_map do |key, values|
+          values.sort.map { |value| [key, value] }
+        end
+      end
+
+      # Normalizes and sorts all request parameters for signing
+      #
+      # @api private
+      # @return [String] normalized request parameters
+      def normalized_params
+        signature_params
+          .map { |key, value| [Header.escape(key), Header.escape(value)] }
+          .sort
+          .map { |pair| pair.join("=") }
+          .join("&")
+      end
+
+      # Collects all parameters to include in signature
+      #
+      # @api private
+      # @return [Array<Array>] all parameters for signature as key-value pairs
+      def signature_params
+        attributes.to_a + expanded_params + url_params
+      end
+
+      # Expands parameters into one pair per value, for parameters with several values
+      #
+      # @api private
+      # @return [Array<Array(Object, Object)>] the parameter pairs
+      def expanded_params
+        params.flat_map do |key, value|
+          value.is_a?(Array) ? value.map { |element| [key, element] } : [[key, value]]
+        end
+      end
+    end
+  end
+end

data/lib/simple_oauth/header.rb

@@ -5,6 +5,7 @@ require_relative "errors"
 require_relative "parser"
 require_relative "signature"
 require_relative "header/class_methods"
+require_relative "header/params"
 
 module SimpleOAuth
   # Generates OAuth 1.0 Authorization headers for HTTP requests
@@ -17,6 +18,8 @@ module SimpleOAuth
     # Prefix for OAuth parameters
     OAUTH_PREFIX = "oauth_".freeze
 
+    # The content type whose body parameters are signed, per RFC 5849 Section 3.4.1.3.1
+    FORM_CONTENT_TYPE = "application/x-www-form-urlencoded".freeze
     # Default signature method per RFC 5849
     DEFAULT_SIGNATURE_METHOD = "HMAC-SHA1".freeze
 
@@ -41,7 +44,7 @@ module SimpleOAuth
 
     # The request parameters to be signed
     #
-    # @return [Hash] the request parameters
+    # @return [Hash, Array<Array(String, Object)>] the request parameters
     # @example
     #   header.params # => {"status" => "Hello"}
     attr_reader :params
@@ -60,6 +63,8 @@ module SimpleOAuth
     #   header.options # => {consumer_key: "key", nonce: "..."}
     attr_reader :options
 
+    include Params
+
     extend ClassMethods
     extend Encoding
 
@@ -68,7 +73,8 @@ module SimpleOAuth
     # @api public
     # @param method [String, Symbol] the HTTP method
     # @param url [String, URI] the request URL
-    # @param params [Hash] the request parameters (for form-encoded bodies)
+    # @param params [Hash, Array<Array(String, Object)>] the request parameters (for form-encoded bodies),
+    #   as a Hash or as an Array of key-value pairs when a key repeats
     # @param oauth [Hash, String] OAuth options hash or an existing Authorization header to parse
     # @param body [String, nil] raw request body for oauth_body_hash (for non-form-encoded bodies)
     # @example Create a header with OAuth options
@@ -117,16 +123,15 @@ module SimpleOAuth
     # @api public
     # @param secrets [Hash] the consumer_secret and token_secret for validation
     # @return [Boolean] true if the signature is valid, false otherwise
+    # @note When the header was built with a body, the signed oauth_body_hash must match that body,
+    #   so a tampered body fails verification even though its signature covers the claimed hash
     # @example
     #   parsed_header = SimpleOAuth::Header.new(:get, url, {}, authorization_header)
     #   parsed_header.valid?(consumer_secret: "secret", token_secret: "token_secret")
     #   # => true
     def valid?(secrets = {})
-      original_options = options.dup #: Hash[Symbol, untyped]
-      options.merge!(secrets)
-      options.fetch(:signature).eql?(signature)
-    ensure
-      options.replace(original_options)
+      body_hash_valid? && Signature.verify(options.fetch(:signature_method), signing_key(options.merge(secrets)),
+        signature_base, options.fetch(:signature))
     end
 
     # Returns the OAuth attributes including the signature
@@ -161,11 +166,10 @@ module SimpleOAuth
     # @param body [String, nil] request body for body_hash computation
     # @return [Hash] merged OAuth options with defaults
     def build_options(oauth, body)
-      if oauth.is_a?(Hash)
-        self.class.default_options(body).merge(oauth.transform_keys(&:to_sym))
-      else
-        self.class.parse(oauth)
-      end
+      return self.class.parse(oauth) unless oauth.is_a?(Hash)
+
+      overrides = oauth.transform_keys(&:to_sym)
+      self.class.default_options(body, overrides.fetch(:signature_method, DEFAULT_SIGNATURE_METHOD)).merge(overrides)
     end
 
     # Builds the normalized OAuth attributes string for the header
@@ -179,29 +183,6 @@ module SimpleOAuth
         .join(", ")
     end
 
-    # Extracts valid OAuth attributes from options
-    #
-    # @api private
-    # @return [Hash] OAuth attributes without signature or realm
-    def attributes
-      validate_option_keys!
-      options.slice(*ATTRIBUTE_KEYS).transform_keys { |key| :"#{OAUTH_PREFIX}#{key}" }
-    end
-
-    # Validates that no unknown keys are present in options
-    #
-    # @api private
-    # @raise [InvalidOptionsError] if extra keys are found
-    # @return [void]
-    def validate_option_keys!
-      return if options[:ignore_extra_keys]
-
-      extra_keys = options.keys - ATTRIBUTE_KEYS - IGNORED_KEYS
-      return if extra_keys.empty?
-
-      raise InvalidOptionsError, "Unknown option keys: #{extra_keys.map(&:inspect).join(", ")}"
-    end
-
     # Returns OAuth attributes with realm for the Authorization header
     #
     # Per RFC 5849 Section 3.5.1, realm is included in the Authorization header
@@ -215,60 +196,54 @@ module SimpleOAuth
       attrs
     end
 
-    # Extracts query parameters from the request URL
-    #
-    # @api private
-    # @return [Array<Array>] URL query parameters as key-value pairs
-    def url_params
-      CGI.parse(@uri.query || "").flat_map do |key, values|
-        values.sort.map { |value| [key, value] }
-      end
-    end
-
     # Computes the OAuth signature using the configured method
     #
     # @api private
     # @return [String] the computed signature based on signature_method
     def signature
-      sig_method = options.fetch(:signature_method)
-      sig_secret = Signature.rsa?(sig_method) ? options[:consumer_secret] : secret
-      Signature.sign(sig_method, sig_secret, signature_base)
+      Signature.sign(options.fetch(:signature_method), signing_key(options), signature_base)
     end
 
-    # Builds the secret string from consumer and token secrets
+    # The key for signing and verifying: an RSA key, or the escaped secrets
     #
     # @api private
-    # @return [String] the secret string for signing
-    def secret
-      options.values_at(:consumer_secret, :token_secret).map { |v| Header.escape(v) }.join("&")
+    # @param options [Hash] the options holding the credentials
+    # @return [String, nil] the key
+    def signing_key(options)
+      Signature.rsa?(options.fetch(:signature_method)) ? options[:consumer_secret] : secret(options)
     end
 
-    # Builds the signature base string from method, URL, and params
+    # Checks the body against the oauth_body_hash the header carries
+    #
+    # A header parsed from a request claims a body hash that its signature covers, so the claim must be
+    # checked against the body actually received. A signer that omits oauth_body_hash leaves the body
+    # unprotected, which its signature already attests to, so there is nothing to check.
     #
     # @api private
-    # @return [String] the signature base string
-    def signature_base
-      [method, url, normalized_params].map { |v| Header.escape(v) }.join("&")
+    # @return [Boolean] true unless the body contradicts the signed oauth_body_hash
+    def body_hash_valid?
+      claimed_body_hash = options[:body_hash]
+      return true if body.nil? || claimed_body_hash.nil?
+
+      digest = Signature.digest(options.fetch(:signature_method))
+      OpenSSL.secure_compare(self.class.body_hash(body, digest), claimed_body_hash)
     end
 
-    # Normalizes and sorts all request parameters for signing
+    # Builds the secret string from consumer and token secrets
     #
     # @api private
-    # @return [String] normalized request parameters
-    def normalized_params
-      signature_params
-        .map { |key, value| [Header.escape(key), Header.escape(value)] }
-        .sort
-        .map { |pair| pair.join("=") }
-        .join("&")
+    # @param options [Hash] the options holding the secrets
+    # @return [String] the secret string for signing
+    def secret(options)
+      options.values_at(:consumer_secret, :token_secret).map { |v| Header.escape(v) }.join("&")
     end
 
-    # Collects all parameters to include in signature
+    # Builds the signature base string from method, URL, and params
     #
     # @api private
-    # @return [Array<Array>] all parameters for signature as key-value pairs
-    def signature_params
-      attributes.to_a + params.to_a + url_params
+    # @return [String] the signature base string
+    def signature_base
+      [method, url, normalized_params].map { |v| Header.escape(v) }.join("&")
     end
   end
 end

data/lib/simple_oauth/signature.rb

@@ -20,6 +20,9 @@ module SimpleOAuth
   #   SimpleOAuth::Signature.registered?("HMAC-SHA1") # => true
   #   SimpleOAuth::Signature.registered?("CUSTOM")    # => false
   module Signature
+    # The hash algorithm of the signature methods RFC 5849 defines
+    DEFAULT_DIGEST = "SHA1".freeze
+
     # Registry of signature method implementations
     @registry = {}
 
@@ -29,6 +32,9 @@ module SimpleOAuth
       # @api public
       # @param name [String] the signature method name (e.g., "HMAC-SHA512")
       # @param rsa [Boolean] whether this method uses RSA (raw consumer_secret as key)
+      # @param verify [Proc, nil] a block that verifies a signature with a key, for methods whose
+      #   signature cannot be recomputed from the verifying key, such as RSA with a public key
+      # @param digest [String] the hash algorithm this method signs with, which oauth_body_hash also uses
       # @yield [secret, signature_base] block that computes the signature
       # @yieldparam secret [String] the signing secret (or PEM key for RSA methods)
       # @yieldparam signature_base [String] the signature base string
@@ -40,8 +46,8 @@ module SimpleOAuth
       #       OpenSSL::HMAC.digest("SHA512", secret, base)
       #     )
       #   end
-      def register(name, rsa: false, &block)
-        @registry[normalize_name(name)] = {implementation: block, rsa: rsa}
+      def register(name, rsa: false, verify: nil, digest: DEFAULT_DIGEST, &block)
+        @registry[normalize_name(name)] = {implementation: block, rsa: rsa, verifier: verify, digest: digest}
       end
 
       # Checks if a signature method is registered
@@ -77,6 +83,18 @@ module SimpleOAuth
         @registry.dig(normalize_name(name), :rsa) || false
       end
 
+      # Returns the hash algorithm a signature method signs with
+      #
+      # @api public
+      # @param name [String] the signature method name
+      # @return [String] the hash algorithm, such as SHA1 or SHA256
+      # @raise [ArgumentError] if the signature method is not registered
+      # @example
+      #   SimpleOAuth::Signature.digest("HMAC-SHA256") # => "SHA256"
+      def digest(name)
+        fetch(name).fetch(:digest)
+      end
+
       # Computes a signature using the specified method
       #
       # @api public
@@ -88,12 +106,26 @@ module SimpleOAuth
       # @example
       #   SimpleOAuth::Signature.sign("HMAC-SHA1", "secret&token", "GET&url&params")
       def sign(name, secret, signature_base)
-        normalized = normalize_name(name)
-        entry = @registry.fetch(normalized) do
-          raise ArgumentError, "Unknown signature method: #{name}. " \
-                               "Registered methods: #{@registry.keys.join(", ")}"
-        end
-        entry.fetch(:implementation).call(secret, signature_base)
+        fetch(name).fetch(:implementation).call(secret, signature_base)
+      end
+
+      # Verifies a signature against a key and a signature base string
+      #
+      # @api public
+      # @param name [String] the signature method name
+      # @param key [String] the verifying key: a public or private RSA key, or the signing secret
+      # @param signature_base [String] the signature base string
+      # @param signature [String] the signature to verify
+      # @return [Boolean] true if the signature is valid
+      # @raise [ArgumentError] if the signature method is not registered
+      # @note Signatures are compared in constant time, so verifying leaks no timing information
+      # @example
+      #   SimpleOAuth::Signature.verify("RSA-SHA1", public_key_pem, "GET&url&params", signature)
+      def verify(name, key, signature_base, signature)
+        verifier = fetch(name).fetch(:verifier)
+        return OpenSSL.secure_compare(sign(name, key, signature_base), signature) if verifier.nil?
+
+        verifier.call(key, signature_base, signature)
       end
 
       # Unregisters a signature method (useful for testing)
@@ -118,6 +150,18 @@ module SimpleOAuth
         register_builtin_methods
       end
 
+      # Decodes Base64-encoded data
+      #
+      # @api public
+      # @param data [String] Base64-encoded data
+      # @return [String] the decoded binary data
+      # @example
+      #   SimpleOAuth::Signature.decode_base64("AQID")
+      #   # => "\x01\x02\x03"
+      def decode_base64(data)
+        Base64.decode64(data)
+      end
+
       # Encodes binary data as Base64 without newlines
       #
       # @api public
@@ -132,6 +176,19 @@ module SimpleOAuth
 
       private
 
+      # Looks up a registered signature method
+      #
+      # @api private
+      # @param name [String] the signature method name
+      # @return [Hash] the registry entry
+      # @raise [ArgumentError] if the signature method is not registered
+      def fetch(name)
+        @registry.fetch(normalize_name(name)) do
+          raise ArgumentError, "Unknown signature method: #{name}. " \
+                               "Registered methods: #{@registry.keys.join(", ")}"
+        end
+      end
+
       # Normalizes signature method name for registry lookup
       #
       # @api private
@@ -157,7 +214,7 @@ module SimpleOAuth
       # @return [void]
       def register_hmac_methods
         %w[SHA1 SHA256].each do |digest|
-          register("HMAC-#{digest}") do |secret, signature_base|
+          register("HMAC-#{digest}", digest: digest) do |secret, signature_base|
             encode_base64(OpenSSL::HMAC.digest(digest, secret, signature_base))
           end
         end
@@ -169,7 +226,10 @@ module SimpleOAuth
       # @return [void]
       def register_rsa_methods
         %w[SHA1 SHA256].each do |digest|
-          register("RSA-#{digest}", rsa: true) do |private_key_pem, signature_base|
+          verifier = lambda { |key_pem, signature_base, signature|
+            OpenSSL::PKey::RSA.new(key_pem).verify(digest, decode_base64(signature), signature_base)
+          }
+          register("RSA-#{digest}", rsa: true, verify: verifier, digest: digest) do |private_key_pem, signature_base|
             private_key = OpenSSL::PKey::RSA.new(private_key_pem)
             encode_base64(private_key.sign(digest, signature_base))
           end

data/lib/simple_oauth/version.rb

@@ -1,5 +1,5 @@
 # OAuth 1.0 header generation library
 module SimpleOauth
   # The current version of the SimpleOAuth gem
-  VERSION = "0.4.1".freeze
+  VERSION = "0.5.0".freeze
 end

data/sig/openssl_ext.rbs

@@ -1,9 +1,15 @@
 # Extensions to OpenSSL types
 module OpenSSL
+  # Compare two strings in constant time
+  def self.secure_compare: (String a, String b) -> bool
+
   module PKey
     class PKey
       # Sign with digest name as String (in addition to Digest object)
       def sign: (String | OpenSSL::Digest digest, String data) -> String
+
+      # Verify with digest name as String (in addition to Digest object)
+      def verify: (String | OpenSSL::Digest digest, String signature, String data) -> bool
     end
   end
 end

data/sig/simple_oauth/header/class_methods.rbs

@@ -1,9 +1,15 @@
 module SimpleOAuth
   class Header
     # Class methods for Header - parsing, defaults, and body hashing
-    module ClassMethods
+    # What the ClassMethods module needs from the class that extends it
+    interface _HeaderFactory
+      def new: (String | Symbol method, String | URI::Generic url, Header::request_params params,
+                ?Header::oauth_options | String oauth, ?String? body) -> Header
+    end
+
+    module ClassMethods : _HeaderFactory
       # Returns default OAuth options with generated nonce and timestamp
-      def default_options: (?String? body) -> Header::oauth_options
+      def default_options: (?String? body, ?String signature_method) -> Header::oauth_options
 
       # Computes the oauth_body_hash for a request body
       def body_hash: (String? body, ?String algorithm) -> String
@@ -12,10 +18,23 @@ module SimpleOAuth
       def parse: (String | _ToS header) -> Header::oauth_options
 
       # Parses OAuth parameters from a form-encoded POST body
+      # Builds a header for an HTTP request
+      def from_request: (Header::_Request request, ?Header::oauth_options | String oauth) -> Header
+
+      # Parses OAuth parameters from a query string
+      def parse_query: (String | _ToS body) -> Hash[Symbol, String]
+
       def parse_form_body: (String | _ToS body) -> Header::oauth_options
 
       private
 
+      # Checks whether a request carries a form-encoded body
+      def form_encoded?: (Header::_Request request) -> bool
+
+      # Extracts the media type from a request, without its parameters
+      def media_type: (Header::_Request request) -> String
+
+
       # Generates a random nonce for OAuth requests
       def generate_nonce: () -> String
 

data/sig/simple_oauth/header/params.rbs

@@ -0,0 +1,29 @@
+module SimpleOAuth
+  class Header
+    # What the Params module needs from the header that includes it
+    interface _Signable
+      def options: () -> Header::oauth_options
+      def params: () -> Header::request_params
+    end
+
+    # Normalization of the parameters that are signed
+    module Params : _Signable
+      @uri: URI::Generic
+
+      private
+
+      # Extracts query parameters from the request URL
+      def url_params: () -> Array[untyped]
+      # Normalizes and sorts all request parameters for signing
+      def normalized_params: () -> String
+      # Collects all parameters to include in signature
+      def signature_params: () -> Array[untyped]
+      # Expands parameters into one pair per value, for parameters with several values
+      def expanded_params: () -> Array[untyped]
+      # Extracts valid OAuth attributes from options (excludes realm per RFC 5849)
+      def attributes: () -> Header::signed_attributes_hash
+      # Validates that no unknown keys are present in options
+      def validate_option_keys!: () -> void
+    end
+  end
+end

data/sig/simple_oauth/signature.rbs

@@ -5,16 +5,22 @@
 module SimpleOAuth
   module Signature
     # Type for signature implementation block
-    type signature_block = ^(String secret, String signature_base) -> String
+    type signature_block = ^(untyped secret, String signature_base) -> String
+
+    # Type for a block that verifies a signature with a key
+    type verifier_block = ^(untyped key, String signature_base, String signature) -> bool
 
     # Type for registry entry
-    type registry_entry = { implementation: signature_block, rsa: bool }
+    type registry_entry = { implementation: signature_block, rsa: bool, verifier: verifier_block?, digest: String }
+
+    # The hash algorithm of the signature methods RFC 5849 defines
+    DEFAULT_DIGEST: String
 
     # Registry of signature method implementations (class-level instance variable)
     self.@registry: Hash[String, registry_entry]
 
     # Registers a custom signature method
-    def self.register: (String | Symbol name, ?rsa: bool) { (String, String) -> String } -> void
+    def self.register: (String | Symbol name, ?rsa: bool, ?verify: verifier_block?, ?digest: String) { (untyped, String) -> String } -> void
 
     # Checks if a signature method is registered
     def self.registered?: (String | Symbol name) -> bool
@@ -25,9 +31,15 @@ module SimpleOAuth
     # Checks if a signature method uses RSA
     def self.rsa?: (String | Symbol name) -> bool
 
+    # Returns the hash algorithm a signature method signs with
+    def self.digest: (String | Symbol name) -> String
+
     # Computes a signature using the specified method
     def self.sign: (String | Symbol name, String? secret, String signature_base) -> String
 
+    # Verifies a signature against a key and a signature base string
+    def self.verify: (String | Symbol name, String? key, String signature_base, String signature) -> bool
+
     # Unregisters a signature method
     def self.unregister: (String | Symbol name) -> void
 
@@ -37,8 +49,14 @@ module SimpleOAuth
     # Encodes binary data as Base64 without newlines
     def self.encode_base64: (String data) -> String
 
+    # Decodes Base64-encoded data
+    def self.decode_base64: (String data) -> String
+
     private
 
+    # Looks up a registered signature method
+    def self.fetch: (String | Symbol name) -> registry_entry
+
     # Normalizes signature method name for registry lookup
     def self.normalize_name: (String | Symbol name) -> String
 

data/sig/simple_oauth.rbs

@@ -40,6 +40,9 @@ module SimpleOAuth
     # Prefix for OAuth parameters
     OAUTH_PREFIX: String
 
+    # The content type whose body parameters are signed
+    FORM_CONTENT_TYPE: String
+
     # Default signature method per RFC 5849
     DEFAULT_SIGNATURE_METHOD: String
 
@@ -55,11 +58,21 @@ module SimpleOAuth
     # Valid keys when parsing OAuth parameters (ATTRIBUTE_KEYS + signature)
     PARSE_KEYS: Array[Symbol]
 
+    # What from_request needs from a request object, such as a Net::HTTPRequest
+    interface _Request
+      def method: () -> String
+      def uri: () -> URI::Generic?
+      def body: () -> String?
+      def []: (String name) -> String?
+    end
+
     # Type aliases for clarity
     type oauth_key = :body_hash | :callback | :consumer_key | :nonce | :signature_method | :timestamp | :token | :verifier | :version
     type ignored_key = :consumer_secret | :token_secret | :signature | :realm | :ignore_extra_keys
     type signature_method = "HMAC-SHA1" | "HMAC-SHA256" | "RSA-SHA1" | "RSA-SHA256" | "PLAINTEXT"
     type params_hash = Hash[String | Symbol, untyped]
+    type params_pairs = Array[[String | Symbol, untyped]]
+    type request_params = params_hash | params_pairs
     type oauth_options = Hash[Symbol, untyped]
     type signed_attributes_hash = Hash[Symbol, untyped]
 
@@ -67,7 +80,7 @@ module SimpleOAuth
     attr_reader method: String
 
     # The request parameters to be signed
-    attr_reader params: params_hash
+    attr_reader params: request_params
 
     # The raw request body for oauth_body_hash computation
     attr_reader body: String?
@@ -75,6 +88,9 @@ module SimpleOAuth
     # The OAuth options including credentials and signature
     attr_reader options: oauth_options
 
+    # Parameter and attribute normalization from the Params module
+    include Params
+
     # Class methods from ClassMethods module
     extend ClassMethods
 
@@ -94,7 +110,7 @@ module SimpleOAuth
     def self.decode: (String | _ToS value) -> String
 
     # Creates a new OAuth header
-    def initialize: (String | Symbol method, String | URI::Generic url, params_hash params, ?oauth_options | String oauth, ?String? body) -> void
+    def initialize: (String | Symbol method, String | URI::Generic url, request_params params, ?oauth_options | String oauth, ?String? body) -> void
 
     # Returns the normalized URL without query string or fragment
     def url: () -> String
@@ -122,32 +138,24 @@ module SimpleOAuth
     # Builds the normalized OAuth attributes string for the Authorization header
     def normalized_attributes: () -> String
 
-    # Extracts valid OAuth attributes from options (excludes realm per RFC 5849)
-    def attributes: () -> signed_attributes_hash
-
-    # Validates that no unknown keys are present in options
-    def validate_option_keys!: () -> void
-
     # Returns OAuth attributes including realm for Authorization header output
     def header_attributes: () -> signed_attributes_hash
 
-    # Extracts query parameters from the request URL
-    def url_params: () -> Array[untyped]
+    # The key for signing and verifying
+    def signing_key: (oauth_options options) -> String?
+
+    # Checks the body against the oauth_body_hash the header carries
+    def body_hash_valid?: () -> bool
 
     # Computes the OAuth signature using the configured signature method
     def signature: () -> String
 
     # Builds the secret string from consumer and token secrets
-    def secret: () -> String
+    def secret: (oauth_options options) -> String
 
     # Builds the signature base string from method, URL, and params
     def signature_base: () -> String
 
-    # Normalizes and sorts all request parameters for signing
-    def normalized_params: () -> String
-
-    # Collects all parameters to include in signature
-    def signature_params: () -> Array[untyped]
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simple_oauth
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.5.0
 platform: ruby
 authors:
 - Steve Richert
@@ -59,6 +59,7 @@ files:
 - lib/simple_oauth/errors.rb
 - lib/simple_oauth/header.rb
 - lib/simple_oauth/header/class_methods.rb
+- lib/simple_oauth/header/params.rb
 - lib/simple_oauth/parser.rb
 - lib/simple_oauth/signature.rb
 - lib/simple_oauth/version.rb
@@ -67,6 +68,7 @@ files:
 - sig/openssl_ext.rbs
 - sig/simple_oauth.rbs
 - sig/simple_oauth/header/class_methods.rbs
+- sig/simple_oauth/header/params.rbs
 - sig/simple_oauth/parser.rbs
 - sig/simple_oauth/signature.rbs
 - sig/strscan.rbs
@@ -94,7 +96,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Simply builds and verifies OAuth headers
 test_files: []