simple_oauth 0.5.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 680161f3f3fc8cf54f78c5111c1f0c4bcd6380b0d29022fb9ac5fd407805d8b7
-  data.tar.gz: 6951095c0b1b04b7755e8857a977946825053a141e3fd4c1c3b7e10cade061fe
+  metadata.gz: 86b6ff6f62fce7e9cc8119852cbf8470c5a1b7f9ab4ecaaf929d2aba35121a2b
+  data.tar.gz: c40d43c6172cf63cca3d04f81291b8e9917062cea0c0b112943cb0a2428c488c
 SHA512:
-  metadata.gz: f852606e3aa48e70a5856f0cfccbfafe4c9235a6a701faca692446186b5bf8f30781b316577b7ac15a164b07293f9b550ad5cdfe0db58df6e57be396de380cf6
-  data.tar.gz: d938005d0ad30817b294e0e8143b272be0dafb794dfa4a57ee012fc8f162c7d895d85a5a2ae0a57f4bc3b9e50c372fde93ac22b31bc01579ead3deec968f2d2a
+  metadata.gz: fafef85869f766c1d1c19ebceb4e8152741734ce438e3379ff0fd94d15b2a4437d7b19e74fe62506f0ff4214eaf37c64cfffaa979400df0fc49b765f8bc1c325
+  data.tar.gz: b95a19574fdd189c53f1e3d263515533991046f8e29e501f12c0a37c39158351f1376c851d58f751b7efda99b6d4a676be2ce243cc5540e52ab4c7d2ef18870e

data/.rubocop.yml

@@ -48,7 +48,7 @@ Style/Alias:
   EnforcedStyle: prefer_alias_method
 
 Style/FrozenStringLiteralComment:
-  Enabled: false
+  Enabled: true
 
 Style/StringLiterals:
   Enabled: true

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+## [1.0.0] - 2026-09-12
+
+### Changed
+
+* Every file declares `frozen_string_literal: true`, and the explicit `freeze` calls on string literals it makes redundant are gone
+* Drop the `base64` runtime dependency: `pack("m0")` and `unpack1("m")` encode and decode Base64 in core Ruby, so the gem now has no runtime dependencies at all
+* Drop the `cgi` runtime dependency: query strings and form bodies are read with `URI.decode_www_form`, which Ruby ships in every supported version
+* **Breaking**: raise `ParseError` when an Authorization header, form body, or query string repeats an OAuth protocol parameter, which RFC 5849 Section 3.2 does not allow; `Header.parse` previously kept the last value and `Header.parse_form_body` the first, so the two disagreed about which one a request carried
+* **Breaking**: rename `Signature.methods` to `Signature.registered_methods`, so that `Signature.methods` is the module's own method list again
+* **Breaking**: define `VERSION` in `SimpleOAuth`, the module the rest of the library uses, rather than in a second `SimpleOauth` module; `SimpleOauth::VERSION` is gone and `SimpleOAuth::VERSION` now resolves
+* **Breaking**: `Signature.rsa?` raises `ArgumentError` for a signature method that is not registered, as `Signature.digest`, `sign`, and `verify` already do, rather than answering false
+* `SimpleOAuth::Error` is the base of every error the library raises, so `rescue SimpleOAuth::Error` catches `ParseError`, `InvalidOptionsError`, and `OAuth2::Error` alike
+
+### Fixed
+
+* Treat only `&` as a parameter separator when reading a query string or form body; a `;` is part of the value, as every current server reads it, so `?a=1;b=2` no longer signs two parameters where the server sees one
+
+### Added
+
+* OAuth 2.0 request builders and response parsers in `SimpleOAuth::OAuth2`, which make no HTTP requests:
+  * `Client#authorization_url` for the authorization code flow, which names `pkce` so that a client either sends a challenge or says `pkce: nil`, as OAuth 2.1 asks every client for one; a `state` is optional alongside a challenge, and required without one
+  * `Client#authorization_code_request`, `#refresh_token_request`, and `#client_credentials_request` for the token endpoint
+  * `Client#revocation_request` for the revocation endpoint (RFC 7009)
+  * `client_secret_basic` and `client_secret_post` authentication for confidential clients, and public clients without a secret
+  * `PKCE` verifiers with `S256` and `plain` challenges (RFC 7636)
+  * `AuthorizationResponse.parse`, which reads the response an authorization server returns to the redirect URI: it raises the error the server reported, a `state` that is not the one the request sent, an `iss` that is not the expected issuer (RFC 9207), a repeated parameter, or a response with no code
+  * A `params` option on every request builder, for what an extension adds to a request, such as the resource indicator of RFC 8707
+  * `Token.from_response` and `Error.from_response` for token and error responses, rejecting a response whose access token is missing, null, or empty, or whose lifetime is not a number of seconds
+
 ## [0.5.1] - 2026-09-12
 
 ### Fixed
@@ -58,6 +87,9 @@
 
 ### Changed
 
+* **Breaking**: `Signature.rsa?` raises `ArgumentError` for a signature method that is not registered, as `Signature.digest`, `sign`, and `verify` already do, rather than answering false
+* `SimpleOAuth::Error` is the base of every error the library raises, so `rescue SimpleOAuth::Error` catches `ParseError`, `InvalidOptionsError`, and `OAuth2::Error` alike
+
 * Supports Ruby 3.2, 3.3, 3.4, and 4.0
 * Added `base64` and `cgi` as explicit runtime dependencies
 * Migrated test suite from RSpec to Minitest

data/README.md

@@ -7,7 +7,9 @@
 [![Typecheck](https://github.com/laserlemon/simple_oauth/actions/workflows/typecheck.yml/badge.svg)](https://github.com/laserlemon/simple_oauth/actions/workflows/typecheck.yml)
 [![Yardstick](https://github.com/laserlemon/simple_oauth/actions/workflows/yardstick.yml/badge.svg)](https://github.com/laserlemon/simple_oauth/actions/workflows/yardstick.yml)
 
-Simply builds and verifies OAuth headers per [RFC 5849](https://tools.ietf.org/html/rfc5849)
+Simply builds and verifies OAuth 1.0 headers per [RFC 5849](https://tools.ietf.org/html/rfc5849), and builds OAuth 2.0 requests per [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749), [RFC 7636](https://www.rfc-editor.org/rfc/rfc7636), and [RFC 7009](https://www.rfc-editor.org/rfc/rfc7009).
+
+Neither makes HTTP requests: you send what it builds with the HTTP client of your choice.
 
 ## Installation
 
@@ -100,7 +102,8 @@ end
 
 # Check registered methods
 SimpleOAuth::Signature.registered?("HMAC-SHA512") # => true
-SimpleOAuth::Signature.methods # => ["hmac_sha1", "hmac_sha256", "rsa_sha1", "rsa_sha256", "plaintext", "hmac_sha512"]
+SimpleOAuth::Signature.registered_methods
+# => ["hmac_sha1", "hmac_sha256", "rsa_sha1", "rsa_sha256", "plaintext", "hmac_sha512"]
 ```
 
 ### OAuth Request Body Hash
@@ -178,6 +181,117 @@ SimpleOAuth::Signature.register("RSA-SHA512", rsa: true,
 end
 ```
 
+## OAuth 2.0
+
+`SimpleOAuth::OAuth2::Client` builds authorization URLs and the requests for its token and revocation endpoints. Each request is a `SimpleOAuth::OAuth2::Request` with a `method`, `url`, `headers`, and form-encoded `body`, ready to send with any HTTP client.
+
+A client with a secret is confidential and authenticates with HTTP Basic, or in the request body with `auth_method: :client_secret_post`. A client without a secret is public and sends only its `client_id`.
+
+`authorization_url` names `pkce` rather than defaulting it, because only the caller can keep the verifier to send with the code. [OAuth 2.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1) asks every client for a PKCE challenge, public and confidential alike, so leaving it out is a decision you make in writing:
+
+```ruby
+# An OAuth 2.0 authorization server that rejects the challenge parameters
+client.authorization_url(redirect_uri: "https://app.example/callback", pkce: nil, state: state)
+```
+
+A PKCE challenge ties the authorization response to the request, which is what `state` does under OAuth 2.0. With a challenge the `state` is yours to use for application state, or to leave out; without one it is required.
+
+### Authorization Code Flow with PKCE
+
+```ruby
+require "net/http"
+require "simple_oauth"
+
+client = SimpleOAuth::OAuth2::Client.new(
+  client_id: "client_id",
+  client_secret: "client_secret", # omit for a public client
+  authorization_endpoint: "https://x.com/i/oauth2/authorize",
+  token_endpoint: "https://api.x.com/2/oauth2/token",
+  revocation_endpoint: "https://api.x.com/2/oauth2/revoke"
+)
+
+# 1. Send the user to authorize the client
+pkce = SimpleOAuth::OAuth2::PKCE.generate
+state = SecureRandom.hex
+redirect_to client.authorization_url(
+  redirect_uri: "https://app.example/callback",
+  pkce: pkce,
+  state: state,
+  scope: %w[tweet.read users.read offline.access]
+)
+
+# 2. Read the response the authorization server returned to the callback
+response = SimpleOAuth::OAuth2::AuthorizationResponse.parse(request.query_string, state: state)
+
+# 3. Exchange the code for a token
+request = client.authorization_code_request(
+  code: response.code,
+  redirect_uri: "https://app.example/callback",
+  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)
+
+token.access_token  # => "..."
+token.refresh_token # => "..."
+token.expires_at    # => 2026-09-11 14:00:00 +0000
+```
+
+`AuthorizationResponse.parse` makes the checks a client owes its own request, raising `SimpleOAuth::OAuth2::Error` rather than returning a code you cannot trust:
+
+* the error the server reported, if it reported one ([RFC 6749 Section 4.1.2.1](https://www.rfc-editor.org/rfc/rfc6749#section-4.1.2.1))
+* a `state` that is not the one the authorization URL sent, compared in constant time
+* an `iss` that is not the expected issuer, when one is given ([RFC 9207](https://www.rfc-editor.org/rfc/rfc9207), which defends against a mix-up between authorization servers)
+* a parameter the response repeats, which RFC 6749 Section 3.1 forbids
+* a response carrying no code at all
+
+```ruby
+SimpleOAuth::OAuth2::AuthorizationResponse.parse(
+  request.query_string,
+  state: session[:state],              # omit when the request sent none
+  issuer: "https://server.example.com" # omit to make no issuer check
+)
+```
+
+It takes the query string, or the parameters a framework already parsed. `Token.from_response` raises `SimpleOAuth::OAuth2::Error` for an error response, with the endpoint's `code`, `description`, `uri`, and HTTP `status`.
+
+### Refreshing, Client Credentials, and Revocation
+
+```ruby
+client.refresh_token_request(refresh_token: token.refresh_token)
+client.client_credentials_request(scope: "read") # confidential clients only
+client.revocation_request(token: token.refresh_token, token_type_hint: "refresh_token")
+
+token.expired?(leeway: 30) # => true within 30 seconds of expiring
+```
+
+Every request builder takes `params` for anything the extension you need adds to the request, such as the resource indicator of [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707):
+
+```ruby
+client.authorization_code_request(
+  code: params[:code],
+  redirect_uri: "https://app.example/callback",
+  code_verifier: pkce.verifier,
+  params: {resource: "https://api.example/"}
+)
+```
+
+These override the parameters the client sends itself, whether their keys are Strings or Symbols.
+
+A revocation endpoint answers 200 when the token is revoked. For any other response, `SimpleOAuth::OAuth2::Error.from_response(status:, body:)` describes the failure.
+
+## Errors
+
+Every error the library raises descends from `SimpleOAuth::Error`, so one rescue covers all of them:
+
+```ruby
+begin
+  token = SimpleOAuth::OAuth2::Token.from_response(status: response.code, body: response.body)
+rescue SimpleOAuth::Error => error
+  # SimpleOAuth::OAuth2::Error, SimpleOAuth::ParseError, or SimpleOAuth::InvalidOptionsError
+end
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/laserlemon/simple_oauth.

data/Rakefile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "bundler/gem_tasks"
 # Override release task to skip gem push (handled by GitHub Actions with attestations)
 Rake::Task["release"].clear

data/Steepfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 D = Steep::Diagnostic
 
 target :lib do
@@ -5,11 +7,10 @@ target :lib do
 
   check "lib"
 
-  library "base64"
   library "openssl"
   library "uri"
-  library "cgi"
   library "securerandom"
+  library "json"
 
   configure_code_diagnostics(D::Ruby.strict) do |hash|
     # Allow FallbackAny warnings for variables in ensure blocks

data/lib/simple_oauth/encoding.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "uri"
 
 module SimpleOAuth

data/lib/simple_oauth/errors.rb

@@ -1,7 +1,12 @@
+# frozen_string_literal: true
+
 module SimpleOAuth
+  # The base of every error the library raises, so one rescue catches them all
+  class Error < StandardError; end
+
   # Error raised when parsing a malformed OAuth Authorization header
-  class ParseError < StandardError; end
+  class ParseError < Error; end
 
   # Error raised when invalid options are passed to Header
-  class InvalidOptionsError < StandardError; end
+  class InvalidOptionsError < Error; end
 end

data/lib/simple_oauth/header/class_methods.rb

@@ -1,5 +1,6 @@
-require "base64"
-require "cgi"
+# frozen_string_literal: true
+
+require "uri"
 require "openssl"
 require "securerandom"
 
@@ -37,7 +38,7 @@ module SimpleOAuth
       #   SimpleOAuth::Header.body_hash('{"text": "Hello"}')
       #   # => "aOjMoMwMP1RZ0hKa1HryYDlCKck="
       def body_hash(body, algorithm = "SHA1")
-        encode_base64(OpenSSL::Digest.digest(algorithm, body || ""))
+        Signature.encode_base64(OpenSSL::Digest.digest(algorithm, body || ""))
       end
 
       # Parses an OAuth Authorization header string into a hash
@@ -71,7 +72,7 @@ module SimpleOAuth
       def from_request(request, oauth = {})
         uri = request.uri || raise(ArgumentError, "The request has no URI")
         body = request.body
-        return new(request.method, uri, form_params(body), oauth) if form_encoded?(request)
+        return new(request.method, uri, form_pairs(body), oauth) if form_encoded?(request)
 
         no_params = {} #: Header::request_params
         new(request.method, uri, no_params, oauth, body)
@@ -85,6 +86,7 @@ module SimpleOAuth
       # @api public
       # @param body [String, #to_s] the form-encoded request body
       # @return [Hash] parsed OAuth attributes with symbol keys (only valid OAuth keys)
+      # @raise [SimpleOAuth::ParseError] if the body repeats a protocol parameter
       # @example
       #   SimpleOAuth::Header.parse_form_body('oauth_consumer_key=key&oauth_signature=sig&status=hello')
       #   # => {consumer_key: "key", signature: "sig"}
@@ -95,11 +97,14 @@ module SimpleOAuth
         valid_keys = PARSE_KEYS.map(&:to_s)
 
         result = {} #: Hash[Symbol, String]
-        CGI.parse(body.to_s).each do |key, values|
+        form_pairs(body).each do |key, value|
           next unless key.start_with?(OAUTH_PREFIX)
 
           parsed_key = key.delete_prefix(OAUTH_PREFIX)
-          result[parsed_key.to_sym] = values.first || "" if valid_keys.include?(parsed_key)
+          next unless valid_keys.include?(parsed_key)
+          raise ParseError, "Duplicate protocol parameter: #{key}" if result.key?(parsed_key.to_sym)
+
+          result[parsed_key.to_sym] = value
         end
         result
       end
@@ -115,23 +120,25 @@ module SimpleOAuth
       #     # => {consumer_key: "key"}
       alias_method :parse_query, :parse_form_body
 
-      private
-
-      # Parses a form-encoded body into the parameter pairs to sign
+      # Parses a form-encoded query string or body into parameter pairs
       #
       # A parameter with no value, such as the "c2" of the RFC 5849 Section 3.4.1.3.1
-      # example, is signed with an empty value rather than dropped.
+      # example, carries an empty value rather than being dropped. An empty segment, as in
+      # the "&&" of "a=1&&b=2", is no parameter at all. Only "&" separates parameters: a
+      # ";" is part of the value, as every current server reads it.
       #
       # @api private
-      # @param body [String, nil] the form-encoded body
+      # @param form [String, #to_s, nil] the form-encoded query string or body
       # @return [Array<Array(String, String)>] the parameter pairs
-      def form_params(body)
-        CGI.parse(body.to_s).flat_map do |key, values|
-          # A parameter with no value still makes one pair, carrying an empty value
-          (values.empty? ? [""] : values).map { |value| [key, value] }
-        end
+      # @example
+      #   SimpleOAuth::Header.form_pairs("c2&a3=2+q")
+      #   # => [["c2", ""], ["a3", "2 q"]]
+      def form_pairs(form)
+        URI.decode_www_form(form.to_s).reject { |key, value| key.empty? && value.empty? }
       end
 
+      private
+
       # Checks whether a request carries a form-encoded body
       #
       # @api private
@@ -160,15 +167,6 @@ module SimpleOAuth
       def generate_nonce
         SecureRandom.hex
       end
-
-      # Encodes binary data as Base64 without newlines
-      #
-      # @api private
-      # @param data [String] binary data to encode
-      # @return [String] Base64-encoded string
-      def encode_base64(data)
-        Base64.strict_encode64(data)
-      end
     end
   end
 end

data/lib/simple_oauth/header/params.rb

@@ -1,4 +1,6 @@
-require "cgi"
+# frozen_string_literal: true
+
+require "uri"
 
 module SimpleOAuth
   class Header
@@ -33,16 +35,14 @@ module SimpleOAuth
 
       # Extracts query parameters from the request URL
       #
-      # A parameter with no value, such as the "c2" of the RFC 5849 Section 3.4.1.3.1
-      # example, is signed with an empty value rather than dropped.
+      # The pairs are left in the order the query string gave them, because
+      # {#normalized_params} sorts every parameter once they are all encoded, which is the
+      # order RFC 5849 Section 3.4.1.3.2 asks for.
       #
       # @api private
       # @return [Array<Array>] URL query parameters as key-value pairs
       def url_params
-        CGI.parse(@uri.query || "").flat_map do |key, values|
-          # A parameter with no value still makes one pair, carrying an empty value
-          (values.empty? ? [""] : values.sort).map { |value| [key, value] }
-        end
+        Header.form_pairs(@uri.query)
       end
 
       # Normalizes and sorts all request parameters for signing

data/lib/simple_oauth/header.rb

@@ -1,4 +1,5 @@
-require "cgi"
+# frozen_string_literal: true
+
 require "uri"
 require_relative "encoding"
 require_relative "errors"
@@ -13,18 +14,18 @@ module SimpleOAuth
   # @api public
   class Header
     # OAuth header scheme prefix
-    OAUTH_SCHEME = "OAuth".freeze
+    OAUTH_SCHEME = "OAuth"
 
     # Prefix for OAuth parameters
-    OAUTH_PREFIX = "oauth_".freeze
+    OAUTH_PREFIX = "oauth_"
 
     # 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
+    FORM_CONTENT_TYPE = "application/x-www-form-urlencoded"
     # Default signature method per RFC 5849
-    DEFAULT_SIGNATURE_METHOD = "HMAC-SHA1".freeze
+    DEFAULT_SIGNATURE_METHOD = "HMAC-SHA1"
 
     # OAuth version
-    OAUTH_VERSION = "1.0".freeze
+    OAUTH_VERSION = "1.0"
 
     # 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

data/lib/simple_oauth/oauth2/authorization_response.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "uri"
+require_relative "error"
+
+module SimpleOAuth
+  module OAuth2
+    # The response an authorization server returns to a client's redirect URI
+    #
+    # Parsing one makes the checks a client owes its own request before it sends the code
+    # anywhere: that the server reported no error, that the response answers the request this
+    # client made, and that it came from the authorization server the client expected.
+    #
+    # @api public
+    # @example Read the code out of a callback
+    #   response = SimpleOAuth::OAuth2::AuthorizationResponse.parse(request.query_string,
+    #     state: session[:state])
+    #   token_request = client.authorization_code_request(code: response.code,
+    #     redirect_uri: "https://app.example/cb", code_verifier: session[:verifier])
+    #
+    # @see https://www.rfc-editor.org/rfc/rfc6749#section-4.1.2 RFC 6749 - Authorization Response
+    # @see https://www.rfc-editor.org/rfc/rfc9207 RFC 9207 - Authorization Server Issuer Identification
+    class AuthorizationResponse
+      # The description of a response whose state is not the one the request sent
+      STATE_MISMATCH = "The authorization response answers a different request"
+      # The description of a response from an authorization server other than the expected one
+      ISSUER_MISMATCH = "The authorization response is from a different authorization server"
+      # The description of a response carrying neither a code nor an error
+      NO_CODE = "The authorization response has no code"
+      # The description of a response that repeats a parameter, which RFC 6749 Section 3.1 forbids
+      DUPLICATE_PARAMETER = "The authorization response repeats a parameter"
+
+      # The authorization code, to exchange for a token
+      #
+      # @api public
+      # @return [String] the authorization code
+      # @example
+      #   response.code # => "SplxlOBeZQQYbYS6WxSbIA"
+      attr_reader :code
+
+      # The state the authorization server returned
+      #
+      # @api public
+      # @return [String, nil] the state
+      # @example
+      #   response.state # => "xyz"
+      attr_reader :state
+
+      # The issuer the authorization server identified itself with (RFC 9207)
+      #
+      # @api public
+      # @return [String, nil] the issuer
+      # @example
+      #   response.issuer # => "https://server.example.com"
+      attr_reader :issuer
+
+      # Every parameter of the authorization response
+      #
+      # @api public
+      # @return [Hash{String => String}] the parameters
+      # @example
+      #   response.params["code"] # => "SplxlOBeZQQYbYS6WxSbIA"
+      attr_reader :params
+
+      # Parse an authorization response, raising unless the client can trust and use it
+      #
+      # @api public
+      # @param query [String, Hash, nil] the query string of the redirect, or its parsed parameters
+      # @param state [String, nil] the state the authorization URL sent, which the response must
+      #   carry; nil to make no such check, for a request that sent none
+      # @param issuer [String, nil] the issuer the server must identify itself with; nil to make
+      #   no such check
+      # @return [AuthorizationResponse] the response
+      # @raise [Error] if the server reported an error, or the response cannot be trusted
+      # @example
+      #   SimpleOAuth::OAuth2::AuthorizationResponse.parse("code=abc&state=xyz", state: "xyz")
+      def self.parse(query, state: nil, issuer: nil)
+        params = parameters(query)
+        raise reported_error(params) if params.key?("error")
+
+        reason = mismatch_reason(params, state, issuer)
+        raise Error.new(code: nil, description: reason) if reason
+
+        new(params)
+      end
+
+      # The parameters of an authorization response
+      #
+      # @api private
+      # @param query [String, Hash, nil] the query string of the redirect, or its parsed parameters
+      # @return [Hash{String => String}] the parameters
+      # @raise [Error] if a parameter is repeated, which RFC 6749 Section 3.1 forbids
+      # @example
+      #   SimpleOAuth::OAuth2::AuthorizationResponse.parameters("code=abc") # => {"code" => "abc"}
+      def self.parameters(query)
+        return query.transform_keys(&:to_s) if query.is_a?(Hash)
+
+        pairs = URI.decode_www_form(query.to_s)
+        raise Error.new(code: nil, description: DUPLICATE_PARAMETER) if pairs.length > pairs.uniq(&:first).length
+
+        pairs.to_h
+      end
+
+      # The error the authorization server reported (RFC 6749 Section 4.1.2.1)
+      #
+      # @api private
+      # @param params [Hash] the response parameters
+      # @return [Error] the error
+      # @example
+      #   SimpleOAuth::OAuth2::AuthorizationResponse.reported_error({"error" => "access_denied"})
+      def self.reported_error(params)
+        Error.new(code: params["error"], description: params["error_description"], uri: params["error_uri"])
+      end
+
+      # The reason a response cannot be trusted or used, if there is one
+      #
+      # @api private
+      # @param params [Hash] the response parameters
+      # @param state [String, nil] the state the request sent
+      # @param issuer [String, nil] the expected issuer
+      # @return [String, nil] the reason, or nil if the response is usable
+      # @example
+      #   SimpleOAuth::OAuth2::AuthorizationResponse.mismatch_reason({"code" => "a"}, nil, nil) # => nil
+      def self.mismatch_reason(params, state, issuer)
+        return STATE_MISMATCH unless matches?(state, params["state"])
+        return ISSUER_MISMATCH unless matches?(issuer, params["iss"])
+
+        NO_CODE if params["code"].to_s.empty?
+      end
+
+      # Whether the response carries what the client expected, in constant time
+      #
+      # @api private
+      # @param expected [String, nil] what the client expects, or nil to expect anything
+      # @param actual [String, nil] what the response carried
+      # @return [Boolean] true if the response is acceptable
+      # @example
+      #   SimpleOAuth::OAuth2::AuthorizationResponse.matches?("xyz", "xyz") # => true
+      def self.matches?(expected, actual)
+        return true if expected.nil?
+
+        !actual.nil? && OpenSSL.secure_compare(expected, actual)
+      end
+
+      # Initialize a response from the parameters of an authorization response
+      #
+      # @api public
+      # @param params [Hash] the response parameters
+      # @raise [KeyError] if the parameters have no code
+      # @example
+      #   SimpleOAuth::OAuth2::AuthorizationResponse.new({"code" => "abc", "state" => "xyz"})
+      def initialize(params)
+        @params = params.transform_keys(&:to_s).freeze
+        @code = @params.fetch("code")
+        @state = @params["state"]
+        @issuer = @params["iss"]
+        freeze
+      end
+    end
+  end
+end