simple_oauth 0.3.1 → 0.4.0

data/lib/simple_oauth/header.rb

@@ -1,133 +1,274 @@
-require 'openssl'
-require 'uri'
-require 'base64'
-require 'cgi'
+require "cgi"
+require "uri"
+require_relative "encoding"
+require_relative "errors"
+require_relative "parser"
+require_relative "signature"
+require_relative "header/class_methods"
 
 module SimpleOAuth
+  # Generates OAuth 1.0 Authorization headers for HTTP requests
+  #
+  # @api public
   class Header
-    ATTRIBUTE_KEYS = [:callback, :consumer_key, :nonce, :signature_method, :timestamp, :token, :verifier, :version] unless defined? ::SimpleOAuth::Header::ATTRIBUTE_KEYS
+    # OAuth header scheme prefix
+    OAUTH_SCHEME = "OAuth".freeze
 
-    IGNORED_KEYS = [:consumer_secret, :token_secret, :signature] unless defined? ::SimpleOAuth::Header::IGNORED_KEYS
+    # Prefix for OAuth parameters
+    OAUTH_PREFIX = "oauth_".freeze
 
-    attr_reader :method, :params, :options
+    # Default signature method per RFC 5849
+    DEFAULT_SIGNATURE_METHOD = "HMAC-SHA1".freeze
 
-    class << self
-      def default_options
-        {
-          :nonce => OpenSSL::Random.random_bytes(16).unpack('H*')[0],
-          :signature_method => 'HMAC-SHA1',
-          :timestamp => Time.now.to_i.to_s,
-          :version => '1.0',
-        }
-      end
+    # OAuth version
+    OAUTH_VERSION = "1.0".freeze
 
-      def parse(header)
-        header.to_s.sub(/^OAuth\s/, '').split(/,\s*/).inject({}) do |attributes, pair|
-          match = pair.match(/^(\w+)\=\"([^\"]*)\"$/)
-          attributes.merge(match[1].sub(/^oauth_/, '').to_sym => unescape(match[2]))
-        end
-      end
+    # Valid OAuth attribute keys that can be included in the header
+    ATTRIBUTE_KEYS = %i[body_hash callback consumer_key nonce signature_method timestamp token verifier version].freeze
 
-      def escape(value)
-        uri_parser.escape(value.to_s, /[^a-z0-9\-\.\_\~]/i)
-      end
-      alias_method :encode, :escape
+    # Keys that are used internally but should not appear in attributes
+    IGNORED_KEYS = %i[consumer_secret token_secret signature realm ignore_extra_keys].freeze
 
-      def unescape(value)
-        uri_parser.unescape(value.to_s)
-      end
-      alias_method :decode, :unescape
+    # Valid keys when parsing OAuth parameters (ATTRIBUTE_KEYS + signature)
+    PARSE_KEYS = [*ATTRIBUTE_KEYS, :signature].freeze
 
-    private
+    # The HTTP method for the request
+    #
+    # @return [String] the HTTP method (GET, POST, etc.)
+    # @example
+    #   header.method # => "GET"
+    attr_reader :method
 
-      def uri_parser
-        @uri_parser ||= URI.const_defined?(:Parser) ? URI::Parser.new : URI
-      end
-    end
+    # The request parameters to be signed
+    #
+    # @return [Hash] the request parameters
+    # @example
+    #   header.params # => {"status" => "Hello"}
+    attr_reader :params
+
+    # The raw request body for oauth_body_hash computation
+    #
+    # @return [String, nil] the request body
+    # @example
+    #   header.body # => '{"text": "Hello"}'
+    attr_reader :body
+
+    # The OAuth options including credentials and signature
+    #
+    # @return [Hash] the OAuth options
+    # @example
+    #   header.options # => {consumer_key: "key", nonce: "..."}
+    attr_reader :options
 
-    def initialize(method, url, params, oauth = {})
+    extend ClassMethods
+    extend Encoding
+
+    # Creates a new OAuth header
+    #
+    # @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 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
+    #   SimpleOAuth::Header.new(:get, "https://api.example.com/resource", {},
+    #     consumer_key: "key", consumer_secret: "secret")
+    # @example Create a header by parsing an existing Authorization header
+    #   SimpleOAuth::Header.new(:get, "https://api.example.com/resource", {}, existing_header)
+    # @example Create a header with a JSON body (oauth_body_hash will be computed)
+    #   SimpleOAuth::Header.new(:post, "https://api.example.com/resource", {},
+    #     {consumer_key: "key", consumer_secret: "secret"}, '{"text": "Hello"}')
+    def initialize(method, url, params, oauth = {}, body = nil)
       @method = method.to_s.upcase
-      @uri = URI.parse(url.to_s)
-      @uri.scheme = @uri.scheme.downcase
-      @uri.normalize!
-      @uri.fragment = nil
+      @uri = normalize_uri(url)
       @params = params
-      @options = oauth.is_a?(Hash) ? self.class.default_options.merge(oauth) : self.class.parse(oauth)
+      @body = body
+      @options = build_options(oauth, body)
     end
 
+    # Returns the normalized URL without query string or fragment
+    #
+    # @api public
+    # @return [String] the normalized URL
+    # @example
+    #   header = SimpleOAuth::Header.new(:get, "https://api.example.com/path?query=1", {})
+    #   header.url
+    #   # => "https://api.example.com/path"
     def url
-      uri = @uri.dup
-      uri.query = nil
-      uri.to_s
+      @uri.dup.tap { |uri| uri.query = nil }.to_str
     end
 
+    # Returns the OAuth Authorization header string
+    #
+    # @api public
+    # @return [String] the Authorization header value
+    # @example
+    #   header = SimpleOAuth::Header.new(:get, "https://api.example.com/", {},
+    #     consumer_key: "key", consumer_secret: "secret")
+    #   header.to_s
+    #   # => "OAuth oauth_consumer_key=\"key\", oauth_nonce=\"...\", ..."
     def to_s
-      "OAuth #{normalized_attributes}"
+      "#{OAUTH_SCHEME} #{normalized_attributes}"
     end
 
+    # Validates the signature in the header against the provided secrets
+    #
+    # @api public
+    # @param secrets [Hash] the consumer_secret and token_secret for validation
+    # @return [Boolean] true if the signature is valid, false otherwise
+    # @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
+      original_options = options.dup #: Hash[Symbol, untyped]
       options.merge!(secrets)
-      valid = options[:signature] == signature
+      options.fetch(:signature).eql?(signature)
+    ensure
       options.replace(original_options)
-      valid
     end
 
+    # Returns the OAuth attributes including the signature
+    #
+    # @api public
+    # @return [Hash] OAuth attributes with oauth_signature included
+    # @example
+    #   header.signed_attributes
+    #   # => {oauth_consumer_key: "key", oauth_signature: "...", ...}
     def signed_attributes
-      attributes.merge(:oauth_signature => signature)
+      header_attributes.merge(oauth_signature: signature)
     end
 
-  private
+    private
 
-    def normalized_attributes
-      signed_attributes.sort_by { |k, _| k.to_s }.collect { |k, v| %(#{k}="#{self.class.escape(v)}") }.join(', ')
+    # Normalizes and parses a URL into a URI object
+    #
+    # @api private
+    # @param url [String, URI] the URL to normalize
+    # @return [URI::Generic] normalized URI without fragment
+    def normalize_uri(url)
+      URI.parse(url.to_s).tap do |uri|
+        uri.normalize!
+        uri.fragment = nil
+      end
     end
 
-    def attributes
-      matching_keys, extra_keys = options.keys.partition { |key| ATTRIBUTE_KEYS.include?(key) }
-      extra_keys -= IGNORED_KEYS
-      if options[:ignore_extra_keys] || extra_keys.empty?
-        Hash[options.select { |key, _| matching_keys.include?(key) }.collect { |key, value| [:"oauth_#{key}", value] }]
+    # Builds OAuth options from input (hash or header string)
+    #
+    # @api private
+    # @param oauth [Hash, String] OAuth options hash or Authorization header
+    # @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
-        fail "SimpleOAuth: Found extra option keys not matching ATTRIBUTE_KEYS:\n  [#{extra_keys.collect(&:inspect).join(', ')}]"
+        self.class.parse(oauth)
       end
     end
 
-    def signature
-      send(options[:signature_method].downcase.tr('-', '_') + '_signature')
+    # Builds the normalized OAuth attributes string for the header
+    #
+    # @api private
+    # @return [String] normalized OAuth attributes for the header
+    def normalized_attributes
+      signed_attributes
+        .sort_by { |key, _| key }
+        .map { |key, value| "#{key}=\"#{Header.escape(value)}\"" }
+        .join(", ")
     end
 
-    def hmac_sha1_signature
-      Base64.encode64(OpenSSL::HMAC.digest(OpenSSL::Digest::SHA1.new, secret, signature_base)).chomp.gsub(/\n/, '')
+    # 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
 
-    def secret
-      options.values_at(:consumer_secret, :token_secret).collect { |v| self.class.escape(v) }.join('&')
+    # 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
-    alias_method :plaintext_signature, :secret
 
-    def signature_base
-      [method, url, normalized_params].collect { |v| self.class.escape(v) }.join('&')
+    # Returns OAuth attributes with realm for the Authorization header
+    #
+    # Per RFC 5849 Section 3.5.1, realm is included in the Authorization header
+    # but excluded from signature calculation (Section 3.4.1.3.1)
+    #
+    # @api private
+    # @return [Hash] OAuth attributes with realm if present
+    def header_attributes
+      attrs = attributes
+      attrs[:realm] = options.fetch(:realm) if options[:realm]
+      attrs
     end
 
-    def normalized_params
-      signature_params.collect { |p| p.collect { |v| self.class.escape(v) } }.sort.collect { |p| p.join('=') }.join('&')
+    # 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
 
-    def signature_params
-      attributes.to_a + params.to_a + url_params
+    # 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)
     end
 
-    def url_params
-      CGI.parse(@uri.query || '').inject([]) { |p, (k, vs)| p + vs.sort.collect { |v| [k, v] } }
+    # Builds the secret string from consumer and token 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("&")
+    end
+
+    # Builds the signature base string from method, URL, and params
+    #
+    # @api private
+    # @return [String] the signature base string
+    def signature_base
+      [method, url, normalized_params].map { |v| Header.escape(v) }.join("&")
     end
 
-    def rsa_sha1_signature
-      Base64.encode64(private_key.sign(OpenSSL::Digest::SHA1.new, signature_base)).chomp.gsub(/\n/, '')
+    # 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
 
-    def private_key
-      OpenSSL::PKey::RSA.new(options[:consumer_secret])
+    # 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 + params.to_a + url_params
     end
   end
 end

data/lib/simple_oauth/parser.rb

@@ -0,0 +1,107 @@
+require "strscan"
+require_relative "errors"
+
+module SimpleOAuth
+  # Parses OAuth Authorization headers
+  #
+  # @api private
+  class Parser
+    # Pattern to match OAuth key-value pairs: key="value"
+    PARAM_PATTERN = /(\w+)="([^"]*)"\s*(,?)\s*/
+
+    # OAuth scheme prefix
+    OAUTH_PREFIX = /OAuth\s+/
+
+    # The StringScanner instance for parsing the header
+    #
+    # @return [StringScanner] the scanner
+    attr_reader :scanner
+
+    # The parsed OAuth attributes
+    #
+    # @return [Hash{Symbol => String}] the parsed attributes
+    attr_reader :attributes
+
+    # Creates a new Parser for the given header string
+    #
+    # @param header [String, #to_s] the OAuth Authorization header string
+    # @return [Parser] a new parser instance
+    def initialize(header)
+      @scanner = StringScanner.new(header.to_s)
+      @attributes = {}
+    end
+
+    # Parses the OAuth Authorization header
+    #
+    # @param valid_keys [Array<Symbol>] the valid OAuth parameter keys
+    # @return [Hash{Symbol => String}] the parsed attributes
+    # @raise [SimpleOAuth::ParseError] if the header is malformed
+    def parse(valid_keys)
+      scan_oauth_prefix
+      scan_params(valid_keys)
+      verify_complete
+      attributes
+    end
+
+    private
+
+    # Scans and validates the OAuth prefix
+    #
+    # @return [void]
+    # @raise [SimpleOAuth::ParseError] if the header doesn't start with "OAuth "
+    def scan_oauth_prefix
+      return if scanner.scan(OAUTH_PREFIX)
+
+      raise ParseError, "Authorization header must start with 'OAuth '"
+    end
+
+    # Scans all key-value parameters from the header
+    #
+    # @param valid_keys [Array<Symbol>] the valid OAuth parameter keys
+    # @return [void]
+    def scan_params(valid_keys)
+      while scanner.scan(PARAM_PATTERN)
+        key = scanner[1] #: String
+        value = scanner[2] #: String
+        comma = scanner[3] #: String
+        validate_comma_separator(key, comma)
+        store_if_valid(key, value, valid_keys)
+      end
+    end
+
+    # Validates that a comma separator exists between parameters
+    #
+    # @param key [String] the parameter key for error messages
+    # @param comma [String] the comma separator (empty string if missing)
+    # @return [void]
+    # @raise [SimpleOAuth::ParseError] if comma is missing and more content follows
+    def validate_comma_separator(key, comma)
+      return if !comma.empty? || scanner.eos?
+
+      raise ParseError,
+        "Expected comma after '#{key}' parameter at position #{scanner.pos}: #{scanner.rest.inspect}"
+    end
+
+    # Stores the parameter if it's a valid OAuth key
+    #
+    # @param key [String] the raw parameter key (e.g., "oauth_consumer_key")
+    # @param value [String] the parameter value
+    # @param valid_keys [Array<Symbol>] the valid OAuth parameter keys
+    # @return [void]
+    def store_if_valid(key, value, valid_keys)
+      parsed_key = valid_keys.find { |k| "oauth_#{k}".eql?(key) }
+      attributes[parsed_key] = Header.unescape(value) if parsed_key
+    end
+
+    # Verifies that the entire header was parsed
+    #
+    # @return [void]
+    # @raise [SimpleOAuth::ParseError] if unparsed content remains
+    def verify_complete
+      return if scanner.eos?
+
+      raise ParseError,
+        "Could not parse parameter at position #{scanner.pos}: #{scanner.rest.inspect}"
+    end
+  end
+end

data/lib/simple_oauth/signature.rb

@@ -0,0 +1,191 @@
+require "base64"
+require "openssl"
+
+module SimpleOAuth
+  # Signature computation methods for OAuth 1.0
+  #
+  # This module provides a registry of signature methods that can be extended
+  # with custom implementations. Built-in methods include HMAC-SHA1, HMAC-SHA256,
+  # RSA-SHA1, RSA-SHA256, and PLAINTEXT.
+  #
+  # @api public
+  # @example Register a custom signature method
+  #   SimpleOAuth::Signature.register("HMAC-SHA512") do |secret, signature_base|
+  #     SimpleOAuth::Signature.encode_base64(
+  #       OpenSSL::HMAC.digest("SHA512", secret, signature_base)
+  #     )
+  #   end
+  #
+  # @example Check if a signature method is registered
+  #   SimpleOAuth::Signature.registered?("HMAC-SHA1") # => true
+  #   SimpleOAuth::Signature.registered?("CUSTOM")    # => false
+  module Signature
+    # Registry of signature method implementations
+    @registry = {}
+
+    class << self
+      # Registers a custom signature method
+      #
+      # @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)
+      # @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
+      # @yieldreturn [String] the computed signature
+      # @return [void]
+      # @example
+      #   SimpleOAuth::Signature.register("HMAC-SHA512") do |secret, base|
+      #     SimpleOAuth::Signature.encode_base64(
+      #       OpenSSL::HMAC.digest("SHA512", secret, base)
+      #     )
+      #   end
+      def register(name, rsa: false, &block)
+        @registry[normalize_name(name)] = {implementation: block, rsa: rsa}
+      end
+
+      # Checks if a signature method is registered
+      #
+      # @api public
+      # @param name [String] the signature method name
+      # @return [Boolean] true if the method is registered
+      # @example
+      #   SimpleOAuth::Signature.registered?("HMAC-SHA1") # => true
+      def registered?(name)
+        @registry.key?(normalize_name(name))
+      end
+
+      # Returns list of registered signature method names
+      #
+      # @api public
+      # @return [Array<String>] registered method names
+      # @example
+      #   SimpleOAuth::Signature.methods # => ["hmac_sha1", "hmac_sha256", "rsa_sha1", "plaintext"]
+      def methods
+        @registry.keys
+      end
+
+      # Checks if a signature method uses RSA (raw key instead of escaped secret)
+      #
+      # @api public
+      # @param name [String] the signature method name
+      # @return [Boolean] true if the method uses RSA
+      # @example
+      #   SimpleOAuth::Signature.rsa?("RSA-SHA1")  # => true
+      #   SimpleOAuth::Signature.rsa?("HMAC-SHA1") # => false
+      def rsa?(name)
+        @registry.dig(normalize_name(name), :rsa) || false
+      end
+
+      # Computes a signature using the specified method
+      #
+      # @api public
+      # @param name [String] the signature method name
+      # @param secret [String] the signing secret
+      # @param signature_base [String] the signature base string
+      # @return [String] the computed signature
+      # @raise [ArgumentError] if the signature method is not registered
+      # @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)
+      end
+
+      # Unregisters a signature method (useful for testing)
+      #
+      # @api public
+      # @param name [String] the signature method name to remove
+      # @return [void]
+      # @example
+      #   SimpleOAuth::Signature.unregister("HMAC-SHA512")
+      def unregister(name)
+        @registry.delete(normalize_name(name))
+      end
+
+      # Resets the registry to only built-in methods (useful for testing)
+      #
+      # @api public
+      # @return [void]
+      # @example
+      #   SimpleOAuth::Signature.reset!
+      def reset!
+        @registry.clear
+        register_builtin_methods
+      end
+
+      # Encodes binary data as Base64 without newlines
+      #
+      # @api public
+      # @param data [String] binary data to encode
+      # @return [String] Base64-encoded string without newlines
+      # @example
+      #   SimpleOAuth::Signature.encode_base64("\x01\x02\x03")
+      #   # => "AQID"
+      def encode_base64(data)
+        Base64.strict_encode64(data)
+      end
+
+      private
+
+      # Normalizes signature method name for registry lookup
+      #
+      # @api private
+      # @param name [String] the signature method name
+      # @return [String] normalized name (lowercase, dashes to underscores)
+      def normalize_name(name)
+        name.to_s.downcase.tr("-", "_")
+      end
+
+      # Registers the built-in OAuth signature methods
+      #
+      # @api private
+      # @return [void]
+      def register_builtin_methods
+        register_hmac_methods
+        register_rsa_methods
+        register_plaintext_method
+      end
+
+      # Registers HMAC-based signature methods
+      #
+      # @api private
+      # @return [void]
+      def register_hmac_methods
+        %w[SHA1 SHA256].each do |digest|
+          register("HMAC-#{digest}") do |secret, signature_base|
+            encode_base64(OpenSSL::HMAC.digest(digest, secret, signature_base))
+          end
+        end
+      end
+
+      # Registers RSA-based signature methods
+      #
+      # @api private
+      # @return [void]
+      def register_rsa_methods
+        %w[SHA1 SHA256].each do |digest|
+          register("RSA-#{digest}", rsa: true) do |private_key_pem, signature_base|
+            private_key = OpenSSL::PKey::RSA.new(private_key_pem)
+            encode_base64(private_key.sign(digest, signature_base))
+          end
+        end
+      end
+
+      # Registers the PLAINTEXT signature method
+      #
+      # @api private
+      # @return [void]
+      def register_plaintext_method
+        register("PLAINTEXT") { |secret, _| secret }
+      end
+    end
+
+    # Initialize built-in methods on load
+    register_builtin_methods
+  end
+end

data/lib/simple_oauth/version.rb

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

data/lib/simple_oauth.rb

@@ -1 +1,30 @@
-require 'simple_oauth/header'
+require_relative "simple_oauth/header"
+require_relative "simple_oauth/version"
+
+# OAuth 1.0 header generation and parsing library
+#
+# SimpleOAuth provides a simple interface for building and verifying
+# OAuth 1.0 Authorization headers per RFC 5849.
+#
+# @example Building an OAuth header
+#   header = SimpleOAuth::Header.new(
+#     :get,
+#     "https://api.example.com/resource",
+#     {status: "Hello"},
+#     consumer_key: "key",
+#     consumer_secret: "secret"
+#   )
+#   header.to_s # => "OAuth oauth_consumer_key=\"key\", ..."
+#
+# @example Parsing an OAuth header
+#   parsed = SimpleOAuth::Header.parse('OAuth oauth_consumer_key="key"')
+#   # => {consumer_key: "key"}
+#
+# @see https://tools.ietf.org/html/rfc5849 RFC 5849 - The OAuth 1.0 Protocol
+module SimpleOAuth
+  # Error raised when parsing a malformed OAuth Authorization header
+  class ParseError < StandardError; end
+
+  # Error raised when invalid options are passed to Header
+  # (defined in header.rb, exported here for convenience)
+end