simple_oauth 0.5.1 → 1.0.0

data/lib/simple_oauth/oauth2/token.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+require_relative "error"
+require_relative "response_body"
+
+module SimpleOAuth
+  module OAuth2
+    # An access token from a successful token response, per RFC 6749 Section 5.1
+    #
+    # @api public
+    # @example Parse a token response
+    #   token = SimpleOAuth::OAuth2::Token.from_response(status: 200, body: response_body)
+    #   token.access_token # => "2YotnFZFEjr1zCsicMWpAA"
+    class Token
+      # The description of a token response that carries no usable access token
+      NO_ACCESS_TOKEN = "token response has no access_token"
+      # The description of a token response whose lifetime is not a number of seconds
+      INVALID_EXPIRES_IN = "token response has an invalid expires_in"
+      # The error message for an access token that cannot be used
+      INVALID_ACCESS_TOKEN = "The access_token must be a non-empty String"
+      # The error message for a token lifetime that is not a number of seconds
+      INVALID_LIFETIME = "The expires_in must be a number of seconds"
+
+      # The access token
+      #
+      # @api public
+      # @return [String] the access token
+      # @example
+      #   token.access_token # => "2YotnFZFEjr1zCsicMWpAA"
+      attr_reader :access_token
+
+      # The token type, such as bearer
+      #
+      # @api public
+      # @return [String, nil] the token type
+      # @example
+      #   token.token_type # => "bearer"
+      attr_reader :token_type
+
+      # The lifetime of the access token in seconds
+      #
+      # @api public
+      # @return [Integer, nil] the lifetime in seconds
+      # @example
+      #   token.expires_in # => 3600
+      attr_reader :expires_in
+
+      # The refresh token, if one was issued
+      #
+      # @api public
+      # @return [String, nil] the refresh token
+      # @example
+      #   token.refresh_token # => "tGzv3JOkF0XG5Qx2TlKWIA"
+      attr_reader :refresh_token
+
+      # The granted scope, as a space-delimited string
+      #
+      # @api public
+      # @return [String, nil] the granted scope
+      # @example
+      #   token.scope # => "tweet.read users.read"
+      attr_reader :scope
+
+      # The time when the access token expires
+      #
+      # @api public
+      # @return [Time, nil] the expiration time
+      # @example
+      #   token.expires_at # => 2026-09-11 13:00:00 UTC
+      attr_reader :expires_at
+
+      # Every parameter of the token response, including nonstandard ones
+      #
+      # @api public
+      # @return [Hash{String => Object}] the parameters
+      # @example
+      #   token.params["example_parameter"] # => "example_value"
+      attr_reader :params
+
+      # Check whether a value is usable as an access token (RFC 6749 Section A.12)
+      #
+      # @api private
+      # @param value [Object] the value from the token response
+      # @return [Boolean] true if the value is a non-empty String
+      # @example
+      #   SimpleOAuth::OAuth2::Token.access_token?("2YotnFZFEjr1zCsicMWpAA") # => true
+      def self.access_token?(value)
+        value.is_a?(String) && !value.empty?
+      end
+
+      # Check whether a value is usable as a token lifetime (RFC 6749 Section 5.1)
+      #
+      # @api private
+      # @param value [Object] the value from the token response
+      # @return [Boolean] true if the value is absent, or a number of seconds
+      # @example
+      #   SimpleOAuth::OAuth2::Token.expires_in?(3600) # => true
+      def self.expires_in?(value)
+        value.nil? || !Integer(value, exception: false).nil?
+      end
+
+      # The reason the parameters of a token response cannot be used, if there is one
+      #
+      # @api private
+      # @param params [Hash] the token response parameters
+      # @return [String, nil] the reason, or nil if the response is usable
+      # @example
+      #   SimpleOAuth::OAuth2::Token.rejection_reason({"access_token" => "abc"}) # => nil
+      def self.rejection_reason(params)
+        return NO_ACCESS_TOKEN unless access_token?(params["access_token"])
+
+        INVALID_EXPIRES_IN unless expires_in?(params["expires_in"])
+      end
+
+      # Parse a token response, raising the endpoint's error if it failed
+      #
+      # @api public
+      # @param status [Integer, String] the HTTP status of the response
+      # @param body [String, nil] the response body
+      # @param issued_at [Time] when the token was issued, used to compute its expiration
+      # @return [Token] the token
+      # @raise [Error] if the response is not successful, or carries no usable token
+      # @raise [ArgumentError] if the status is not an HTTP status
+      # @example
+      #   SimpleOAuth::OAuth2::Token.from_response(status: 200, body: '{"access_token":"abc","token_type":"bearer"}')
+      def self.from_response(status:, body:, issued_at: Time.now)
+        code = Error.http_status(status)
+        raise Error.from_response(status:, body:) unless (200..299).cover?(code)
+
+        params = ResponseBody.parse(body)
+        reason = rejection_reason(params)
+        raise Error.new(code: nil, description: reason, status: code) if reason
+
+        new(params, issued_at:)
+      end
+
+      # Initialize a token from the parameters of a token response
+      #
+      # @api public
+      # @param params [Hash] the token response parameters
+      # @param issued_at [Time] when the token was issued, used to compute its expiration
+      # @raise [KeyError] if the parameters have no access_token
+      # @raise [ArgumentError] if the access token cannot be used, or the lifetime is not a number of seconds
+      # @example
+      #   SimpleOAuth::OAuth2::Token.new({"access_token" => "abc", "expires_in" => 3600})
+      def initialize(params, issued_at: Time.now)
+        @params = params.transform_keys(&:to_s).freeze
+        @access_token = validated_access_token
+        @token_type = @params["token_type"]
+        @expires_in = validated_expires_in
+        @refresh_token = @params["refresh_token"]
+        @scope = @params["scope"]
+        @expires_at = @expires_in&.then { |seconds| issued_at + seconds }
+        freeze
+      end
+
+      # The granted scopes
+      #
+      # @api public
+      # @return [Array<String>] the granted scopes
+      # @example
+      #   token.scopes # => ["tweet.read", "users.read"]
+      def scopes
+        scope.to_s.split
+      end
+
+      # Check whether the access token has expired, or will within a leeway
+      #
+      # @api public
+      # @param leeway [Numeric] seconds before expiration to treat the token as expired
+      # @param now [Time] the current time
+      # @return [Boolean] true if the token has expired; false if it has not or never expires
+      # @example Refresh a token that expires within 30 seconds
+      #   token.expired?(leeway: 30)
+      def expired?(leeway: 0, now: Time.now)
+        return false if expires_at.nil?
+
+        now >= expires_at - leeway
+      end
+
+      private
+
+      # The access token from the parameters, which must be usable
+      #
+      # @api private
+      # @return [String] the access token
+      # @raise [KeyError] if the parameters have no access_token
+      # @raise [ArgumentError] if the access token is not a non-empty String
+      def validated_access_token
+        token = params.fetch("access_token")
+        raise ArgumentError, INVALID_ACCESS_TOKEN unless self.class.access_token?(token)
+
+        token
+      end
+
+      # The lifetime from the parameters, which must be a number of seconds
+      #
+      # @api private
+      # @return [Integer, nil] the lifetime in seconds, or nil if the response carries none
+      # @raise [ArgumentError] if the lifetime is not a number of seconds
+      def validated_expires_in
+        seconds = params["expires_in"]
+        raise ArgumentError, INVALID_LIFETIME unless self.class.expires_in?(seconds)
+
+        seconds && Integer(seconds)
+      end
+    end
+  end
+end

data/lib/simple_oauth/oauth2.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "oauth2/authorization_response"
+require_relative "oauth2/client"
+require_relative "oauth2/error"
+require_relative "oauth2/pkce"
+require_relative "oauth2/request"
+require_relative "oauth2/response_body"
+require_relative "oauth2/token"
+
+module SimpleOAuth
+  # OAuth 2.0 request builders and response parsers
+  #
+  # Like the OAuth 1.0 header builder, these build requests and parse responses without
+  # performing HTTP themselves, so they work with any HTTP client.
+  #
+  # @api public
+  # @example Exchange an authorization code for a token
+  #   client = SimpleOAuth::OAuth2::Client.new(client_id: "id", token_endpoint: "https://example.com/token")
+  #   pkce = SimpleOAuth::OAuth2::PKCE.generate
+  #   request = client.authorization_code_request(code: "code", redirect_uri: "https://app.example/cb",
+  #     code_verifier: pkce.verifier)
+  #   response = Net::HTTP.post(URI(request.url), request.body, request.headers)
+  #   token = SimpleOAuth::OAuth2::Token.from_response(status: response.code, body: response.body)
+  #
+  # @see https://www.rfc-editor.org/rfc/rfc6749 RFC 6749 - The OAuth 2.0 Authorization Framework
+  # @see https://www.rfc-editor.org/rfc/rfc7636 RFC 7636 - Proof Key for Code Exchange (PKCE)
+  # @see https://www.rfc-editor.org/rfc/rfc7009 RFC 7009 - OAuth 2.0 Token Revocation
+  module OAuth2
+  end
+end

data/lib/simple_oauth/parser.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "strscan"
 require_relative "errors"
 
@@ -88,9 +90,13 @@ module SimpleOAuth
     # @param value [String] the parameter value
     # @param valid_keys [Array<Symbol>] the valid OAuth parameter keys
     # @return [void]
+    # @raise [SimpleOAuth::ParseError] if the header repeats the parameter
     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
+      return if parsed_key.nil?
+      raise ParseError, "Duplicate protocol parameter: #{key}" if attributes.key?(parsed_key)
+
+      attributes[parsed_key] = Header.unescape(value)
     end
 
     # Verifies that the entire header was parsed

data/lib/simple_oauth/signature.rb

@@ -1,4 +1,5 @@
-require "base64"
+# frozen_string_literal: true
+
 require "openssl"
 
 module SimpleOAuth
@@ -21,7 +22,7 @@ module SimpleOAuth
   #   SimpleOAuth::Signature.registered?("CUSTOM")    # => false
   module Signature
     # The hash algorithm of the signature methods RFC 5849 defines
-    DEFAULT_DIGEST = "SHA1".freeze
+    DEFAULT_DIGEST = "SHA1"
 
     # Registry of signature method implementations
     @registry = {}
@@ -66,8 +67,9 @@ module SimpleOAuth
       # @api public
       # @return [Array<String>] registered method names
       # @example
-      #   SimpleOAuth::Signature.methods # => ["hmac_sha1", "hmac_sha256", "rsa_sha1", "plaintext"]
-      def methods
+      #   SimpleOAuth::Signature.registered_methods
+      #   # => ["hmac_sha1", "hmac_sha256", "rsa_sha1", "plaintext"]
+      def registered_methods
         @registry.keys
       end
 
@@ -76,11 +78,12 @@ module SimpleOAuth
       # @api public
       # @param name [String] the signature method name
       # @return [Boolean] true if the method uses RSA
+      # @raise [ArgumentError] if the signature method is not registered
       # @example
       #   SimpleOAuth::Signature.rsa?("RSA-SHA1")  # => true
       #   SimpleOAuth::Signature.rsa?("HMAC-SHA1") # => false
       def rsa?(name)
-        @registry.dig(normalize_name(name), :rsa) || false
+        fetch(name).fetch(:rsa)
       end
 
       # Returns the hash algorithm a signature method signs with
@@ -159,7 +162,8 @@ module SimpleOAuth
       #   SimpleOAuth::Signature.decode_base64("AQID")
       #   # => "\x01\x02\x03"
       def decode_base64(data)
-        Base64.decode64(data)
+        # "m" is Base64, and is lenient about characters outside the alphabet
+        data.unpack1("m") #: String
       end
 
       # Encodes binary data as Base64 without newlines
@@ -171,7 +175,8 @@ module SimpleOAuth
       #   SimpleOAuth::Signature.encode_base64("\x01\x02\x03")
       #   # => "AQID"
       def encode_base64(data)
-        Base64.strict_encode64(data)
+        # "m0" is Base64 with no line breaks
+        [data].pack("m0")
       end
 
       private

data/lib/simple_oauth/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 # OAuth 1.0 header generation library
-module SimpleOauth
+module SimpleOAuth
   # The current version of the SimpleOAuth gem
-  VERSION = "0.5.1".freeze
+  VERSION = "1.0.0"
 end

data/lib/simple_oauth.rb

@@ -1,10 +1,14 @@
+# frozen_string_literal: true
+
 require_relative "simple_oauth/header"
+require_relative "simple_oauth/oauth2"
 require_relative "simple_oauth/version"
 
-# OAuth 1.0 header generation and parsing library
+# OAuth 1.0 header and OAuth 2.0 request building library
 #
 # SimpleOAuth provides a simple interface for building and verifying
-# OAuth 1.0 Authorization headers per RFC 5849.
+# OAuth 1.0 Authorization headers per RFC 5849, and for building
+# OAuth 2.0 requests and parsing their responses (see {SimpleOAuth::OAuth2}).
 #
 # @example Building an OAuth header
 #   header = SimpleOAuth::Header.new(
@@ -22,9 +26,4 @@ require_relative "simple_oauth/version"
 #
 # @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

data/sig/simple_oauth/header/class_methods.rbs

@@ -26,10 +26,10 @@ module SimpleOAuth
 
       def parse_form_body: (String | _ToS body) -> Header::oauth_options
 
-      private
+      # Parses a form-encoded query string or body into parameter pairs
+      def form_pairs: (String | _ToS | nil form) -> Array[[String, String]]
 
-      # Parses a form-encoded body into the parameter pairs to sign
-      def form_params: (String? body) -> Array[[String, String]]
+      private
 
       # Checks whether a request carries a form-encoded body
       def form_encoded?: (Header::_Request request) -> bool
@@ -41,8 +41,6 @@ module SimpleOAuth
       # Generates a random nonce for OAuth requests
       def generate_nonce: () -> String
 
-      # Encodes binary data as Base64 without newlines
-      def encode_base64: (String data) -> String
     end
   end
 end

data/sig/simple_oauth/oauth2.rbs

@@ -0,0 +1,144 @@
+module SimpleOAuth
+  # OAuth 2.0 request builders and response parsers
+  module OAuth2
+    # Parses the JSON bodies returned by OAuth 2.0 endpoints
+    module ResponseBody
+      def self.parse: (String? body) -> Hash[String, untyped]
+    end
+
+    # The response an authorization server returns to a client's redirect URI
+    class AuthorizationResponse
+      type response_params = Hash[String | Symbol, String]
+
+      STATE_MISMATCH: String
+      ISSUER_MISMATCH: String
+      NO_CODE: String
+      DUPLICATE_PARAMETER: String
+
+      attr_reader code: String
+      attr_reader state: String?
+      attr_reader issuer: String?
+      attr_reader params: Hash[String, String]
+
+      def self.parse: (String | response_params | nil query, ?state: String?, ?issuer: String?) -> AuthorizationResponse
+      def self.parameters: (String | response_params | nil query) -> Hash[String, String]
+      def self.reported_error: (Hash[String, String] params) -> Error
+      def self.mismatch_reason: (Hash[String, String] params, String? state, String? issuer) -> String?
+      def self.matches?: (String? expected, String? actual) -> bool
+      def initialize: (response_params params) -> void
+    end
+
+    # Error returned by an OAuth 2.0 endpoint
+    class Error < SimpleOAuth::Error
+      INVALID_STATUS: String
+
+      attr_reader code: String?
+      attr_reader description: String?
+      attr_reader uri: String?
+      attr_reader status: Integer?
+
+      def self.http_status: (Integer | String value) -> Integer
+      def self.from_response: (status: Integer | String, body: String?) -> Error
+      def initialize: (code: String?, ?description: String?, ?uri: String?, ?status: Integer?) -> void
+    end
+
+    # A Proof Key for Code Exchange verifier and challenge
+    class PKCE
+      S256: String
+      PLAIN: String
+      VERIFIER_PATTERN: Regexp
+      INVALID_VERIFIER: String
+      VERIFIER_BYTES: Integer
+
+      attr_reader verifier: String
+      attr_reader challenge_method: String
+      attr_reader challenge: String
+
+      def self.generate: (?challenge_method: String) -> PKCE
+      def initialize: (verifier: String, ?challenge_method: String) -> void
+
+      private
+
+      def compute_challenge: () -> String
+      def base64_url: (String data) -> String
+    end
+
+    # An HTTP request to an OAuth 2.0 endpoint, built but not sent
+    class Request
+      attr_reader method: String
+      attr_reader url: String
+      attr_reader headers: Hash[String, String]
+      attr_reader body: String
+
+      def initialize: (method: String, url: String, headers: Hash[String, String], body: String) -> void
+    end
+
+    # An access token from a successful token response
+    class Token
+      NO_ACCESS_TOKEN: String
+      INVALID_EXPIRES_IN: String
+      INVALID_ACCESS_TOKEN: String
+      INVALID_LIFETIME: String
+
+      attr_reader access_token: String
+      attr_reader token_type: String?
+      attr_reader expires_in: Integer?
+      attr_reader refresh_token: String?
+      attr_reader scope: String?
+      attr_reader expires_at: Time?
+      attr_reader params: Hash[String, untyped]
+
+      def self.access_token?: (untyped value) -> bool
+      def self.expires_in?: (untyped value) -> bool
+      def self.rejection_reason: (Hash[String, untyped] params) -> String?
+      def self.from_response: (status: Integer | String, body: String?, ?issued_at: Time) -> Token
+      def initialize: (Hash[String | Symbol, untyped] params, ?issued_at: Time) -> void
+      def scopes: () -> Array[String]
+      def expired?: (?leeway: Numeric, ?now: Time) -> bool
+
+      private
+
+      def validated_access_token: () -> String
+      def validated_expires_in: () -> Integer?
+    end
+
+    # An OAuth 2.0 client that builds authorization URLs and endpoint requests
+    class Client
+      type auth_method = :client_secret_basic | :client_secret_post
+      type scope = String | Array[String] | nil
+      type form_params = Hash[Symbol, String?]
+      type extra_params = Hash[Symbol | String, String?]
+
+      AUTH_METHODS: Array[Symbol]
+      FORM_CONTENT_TYPE: String
+      EMPTY_STATE: String
+      UNPROTECTED: String
+
+      attr_reader client_id: String
+      attr_reader client_secret: String?
+      attr_reader authorization_endpoint: String?
+      attr_reader token_endpoint: String?
+      attr_reader revocation_endpoint: String?
+      attr_reader auth_method: auth_method
+
+      def initialize: (client_id: String, ?client_secret: String?, ?authorization_endpoint: String?, ?token_endpoint: String?,
+                       ?revocation_endpoint: String?, ?auth_method: auth_method) -> void
+      def public?: () -> bool
+      def authorization_url: (redirect_uri: String, pkce: PKCE?, ?state: String?, ?scope: scope, ?params: extra_params) -> String
+      def authorization_code_request: (code: String, redirect_uri: String, ?code_verifier: String?, ?params: extra_params) -> Request
+      def refresh_token_request: (refresh_token: String, ?scope: scope, ?params: extra_params) -> Request
+      def client_credentials_request: (?scope: scope, ?params: extra_params) -> Request
+      def revocation_request: (token: String, ?token_type_hint: String?, ?params: extra_params) -> Request
+
+      private
+
+      def validate_protection!: (PKCE? pkce, String? state) -> void
+      def token_request: (form_params params, extra_params extra) -> Request
+      def form_request: (String url, form_params params, extra_params extra) -> Request
+      def authenticated: (form_params params) -> [Hash[String, String], form_params]
+      def basic_authorization: (String secret) -> String
+      def scope_value: (scope scope) -> String?
+      def endpoint: (String? url, Symbol name) -> String
+    end
+  end
+end

data/sig/simple_oauth/signature.rbs

@@ -26,7 +26,7 @@ module SimpleOAuth
     def self.registered?: (String | Symbol name) -> bool
 
     # Returns list of registered signature method names
-    def self.methods: () -> Array[String]
+    def self.registered_methods: () -> Array[String]
 
     # Checks if a signature method uses RSA
     def self.rsa?: (String | Symbol name) -> bool

data/sig/simple_oauth.rbs

@@ -1,11 +1,15 @@
 # OAuth 1.0 header generation library
 module SimpleOAuth
+  # The base of every error the library raises
+  class Error < StandardError
+  end
+
   # Error raised when parsing a malformed OAuth Authorization header
-  class ParseError < StandardError
+  class ParseError < Error
   end
 
   # Error raised when invalid options are passed to Header
-  class InvalidOptionsError < StandardError
+  class InvalidOptionsError < Error
   end
 
   # OAuth percent-encoding utilities
@@ -160,7 +164,7 @@ module SimpleOAuth
 end
 
 # Version module
-module SimpleOauth
+module SimpleOAuth
   # The current version of the SimpleOAuth gem
   VERSION: String
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: simple_oauth
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Steve Richert
@@ -9,36 +9,8 @@ authors:
 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'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-- !ruby/object:Gem::Dependency
-  name: cgi
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-description: Simply builds and verifies OAuth headers
+dependencies: []
+description: Simply builds and verifies OAuth 1.0 headers and builds OAuth 2.0 requests
 email:
 - steve.richert@gmail.com
 - sferik@gmail.com
@@ -60,6 +32,14 @@ files:
 - lib/simple_oauth/header.rb
 - lib/simple_oauth/header/class_methods.rb
 - lib/simple_oauth/header/params.rb
+- lib/simple_oauth/oauth2.rb
+- lib/simple_oauth/oauth2/authorization_response.rb
+- lib/simple_oauth/oauth2/client.rb
+- lib/simple_oauth/oauth2/error.rb
+- lib/simple_oauth/oauth2/pkce.rb
+- lib/simple_oauth/oauth2/request.rb
+- lib/simple_oauth/oauth2/response_body.rb
+- lib/simple_oauth/oauth2/token.rb
 - lib/simple_oauth/parser.rb
 - lib/simple_oauth/signature.rb
 - lib/simple_oauth/version.rb
@@ -69,6 +49,7 @@ files:
 - sig/simple_oauth.rbs
 - sig/simple_oauth/header/class_methods.rbs
 - sig/simple_oauth/header/params.rbs
+- sig/simple_oauth/oauth2.rbs
 - sig/simple_oauth/parser.rbs
 - sig/simple_oauth/signature.rbs
 - sig/strscan.rbs
@@ -97,5 +78,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.20
 specification_version: 4
-summary: Simply builds and verifies OAuth headers
+summary: Simply builds and verifies OAuth 1.0 headers and builds OAuth 2.0 requests
 test_files: []