standard_id 0.41.0 → 0.42.0

data/lib/standard_id/oauth/oauth_session_persistence.rb

@@ -37,41 +37,83 @@ module StandardId
         end
       end
 
+      # Reuse the device's ACTIVE session row, or start a new one.
+      #
+      # Only a non-revoked row is eligible. Sign-out (/oauth/revoke under the
+      # default :account revocation_scope) revokes every active DeviceSession
+      # for the account; reusing that revoked row on the next sign-in — which a
+      # bare `find_by(account:, device_id:)` did — linked every new refresh
+      # token to a revoked parent, so RefreshTokenFlow#validate_parent_session!
+      # refused the very first refresh and the client was bounced to sign-in
+      # after every access-token expiry, forever. A revoked row is history (the
+      # audit trail and admin session lists still read it); a new sign-in gets
+      # a new row. Expiry is deliberately NOT part of eligibility: an expired
+      # but unrevoked row is reused with its expires_at bumped, as before.
       def upsert_device_session!(account:, request:, audience:, grant_type:)
         user_agent = request.user_agent
         device_id = stable_device_id(account: account, user_agent: user_agent, audience: audience)
         ip_address = StandardId::Utils::IpNormalizer.normalize(request.remote_ip)
 
-        # Serialize concurrent upserts for the same account. There's no
-        # DB-level unique constraint on (account_id, device_id), so a raw
-        # find_by + create! would TOCTOU-race two concurrent token requests
-        # for the same device into two duplicate rows. We acquire a SELECT
-        # ... FOR UPDATE on the account row to serialize — account.with_lock
-        # is unavailable because StandardId::AccountLocking overrides lock!
-        # with a business-level method that takes a :reason kwarg.
-        # The outer transaction (opened by TokenGrantFlow#generate_token_response)
+        # Serialize concurrent upserts for the same account. We acquire a
+        # SELECT ... FOR UPDATE on the account row — account.with_lock is
+        # unavailable because StandardId::AccountLocking overrides lock! with a
+        # business-level method that takes a :reason kwarg. The outer
+        # transaction (opened by TokenGrantFlow#generate_token_response)
         # releases the lock on commit/rollback.
+        #
+        # The lock alone is not the guarantee: the partial unique index from
+        # 20260924000000 (one active row per account + device_id) is. The lock
+        # keeps the common case free of unique violations; the savepoint below
+        # handles the rest, and keeps hosts that have not yet run that
+        # migration no worse off than before.
         account.class.where(id: account.id).lock.first
 
-        existing = StandardId::DeviceSession.find_by(account: account, device_id: device_id)
-        if existing
-          existing.update!(
-            expires_at: StandardId::DeviceSession.expiry,
-            ip_address: ip_address || existing.ip_address,
-            device_agent: user_agent || existing.device_agent
-          )
-          existing
-        else
-          StandardId::DeviceSession.create!(
-            account: account,
-            device_id: device_id,
-            device_agent: user_agent.presence || "OAuth:#{grant_type}",
-            ip_address: ip_address || "0.0.0.0",
-            expires_at: StandardId::DeviceSession.expiry
-          )
+        existing = active_device_session(account: account, device_id: device_id)
+        return refresh_device_session!(existing, ip_address: ip_address, user_agent: user_agent) if existing
+
+        begin
+          # Savepoint, so a unique violation does not abort the enclosing token
+          # transaction (Postgres refuses every later statement in an aborted
+          # transaction).
+          StandardId::DeviceSession.transaction(requires_new: true) do
+            StandardId::DeviceSession.create!(
+              account: account,
+              device_id: device_id,
+              device_agent: user_agent.presence || "OAuth:#{grant_type}",
+              ip_address: ip_address || "0.0.0.0",
+              expires_at: StandardId::DeviceSession.expiry
+            )
+          end
+        rescue ActiveRecord::RecordNotUnique
+          # A concurrent sign-in for the same device committed its row first.
+          # Reuse the winner rather than failing the token request.
+          winner = active_device_session(account: account, device_id: device_id)
+          raise unless winner
+
+          refresh_device_session!(winner, ip_address: ip_address, user_agent: user_agent)
         end
       end
 
+      # Newest first: before the unique index existed, a race could leave two
+      # active rows for one device, and an unordered lookup picked one
+      # arbitrarily. The migration detaches such duplicates, but hosts that
+      # have not run it yet still benefit from a deterministic choice.
+      def active_device_session(account:, device_id:)
+        StandardId::DeviceSession
+          .where(account: account, device_id: device_id, revoked_at: nil)
+          .order(created_at: :desc, id: :desc)
+          .first
+      end
+
+      def refresh_device_session!(session, ip_address:, user_agent:)
+        session.update!(
+          expires_at: StandardId::DeviceSession.expiry,
+          ip_address: ip_address || session.ip_address,
+          device_agent: user_agent || session.device_agent
+        )
+        session
+      end
+
       def stable_device_id(account:, user_agent:, audience:)
         audience_key = Array(audience).join(",")
         Digest::SHA256.hexdigest("oauth:#{audience_key}:#{account.id}:#{user_agent}")[0, 36]

data/lib/standard_id/oauth/refresh_token_flow.rb

@@ -14,7 +14,7 @@ module StandardId
       # Only the normal rotation path (revoke old + create new) is wrapped
       # in a transaction for atomicity.
       def execute
-        authenticate!
+        instrumented_authenticate!
         response = nil
         StandardId::RefreshToken.transaction do
           rotate_current_refresh_token!
@@ -81,6 +81,7 @@ module StandardId
           if (successor = graced_successor_for(@current_refresh_token_record))
             emit_reuse_graced_event(@current_refresh_token_record, successor)
             @current_refresh_token_record = successor
+            @served_from_graced_successor = true
           else
             # Reuse detected: this token was already rotated. Revoke entire family.
             @current_refresh_token_record.revoke_family!
@@ -166,9 +167,24 @@ module StandardId
         raise ActiveRecord::Rollback
       end
 
+      # Only a request that presented the lost-the-race token ITSELF is treated
+      # as reuse. A request served from a graced successor that loses the race
+      # is the leeway's own retry colliding with another retry of the same lost
+      # response — a client re-sending the superseded token twice in quick
+      # succession. Both passed #graced_successor_for while the successor was
+      # untouched; one rotated it. Revoking the family here would kill the
+      # token the winning request just issued and log the honest client out,
+      # which is exactly what the leeway exists to prevent. The loser gets a
+      # plain invalid_grant and the client keeps the winner's response.
+      #
+      # This does not widen the leeway: the winner already consumed the
+      # successor, so a later replay of the superseded token finds a USED
+      # successor and revokes the family as before.
       def handle_concurrent_reuse!
         @current_refresh_token_record&.reload
         if @current_refresh_token_record&.revoked?
+          raise StandardId::InvalidGrantError, "Refresh token is no longer valid" if @served_from_graced_successor
+
           @current_refresh_token_record.revoke_family!
           emit_reuse_detected_event
           raise StandardId::InvalidGrantError, "Refresh token reuse detected"
@@ -208,7 +224,12 @@ module StandardId
         return nil if revoked_record.revoked_at.blank?
         return nil if revoked_record.revoked_at < leeway.seconds.ago
 
-        successor = StandardId::RefreshToken.find_by(previous_token_id: revoked_record.id)
+        # eager_load(:session), matching the primary lookup in
+        # #validate_refresh_token_record!: the successor becomes
+        # @current_refresh_token_record, and #validate_parent_session! reads its
+        # :session. A bare find_by left that a lazy read, which raises
+        # StrictLoadingViolationError (a 500) under strict loading.
+        successor = StandardId::RefreshToken.eager_load(:session).find_by(previous_token_id: revoked_record.id)
         return nil unless successor&.active?
         return nil if StandardId::RefreshToken.exists?(previous_token_id: successor.id)
 

data/lib/standard_id/oauth/token_grant_flow.rb

@@ -16,18 +16,37 @@ module StandardId
       end
 
       def execute
-        authenticate!
+        instrumented_authenticate!
         generate_token_response
       end
 
       private
 
+      # authenticate!, wrapped in the Instrumentation::AUTHENTICATE event.
+      def instrumented_authenticate!
+        StandardId::Instrumentation.instrument(StandardId::Instrumentation::AUTHENTICATE, instrumentation_payload) do
+          authenticate!
+        end
+      end
+
+      def instrumentation_payload
+        { flow: self.class.name, grant_type: instrumentation_grant_type }
+      end
+
+      # Abstract/anonymous flows (specs) may not implement grant_type; the
+      # instrumentation payload must never be what raises.
+      def instrumentation_grant_type
+        grant_type
+      rescue NotImplementedError
+        nil
+      end
+
       def authenticate!
         raise NotImplementedError, "Subclasses must implement authenticate!"
       end
 
       def validate_client_secret!(client_id, client_secret)
-        client_secret_credential = StandardId::ClientSecretCredential.active.find_by(client_id: client_id)
+        client_secret_credential = StandardId::ClientSecretCredential.active.includes(:client_application).find_by(client_id: client_id)
         unless client_secret_credential&.authenticate_client_secret(client_secret)
           raise StandardId::InvalidClientError, "Client authentication failed"
         end
@@ -36,7 +55,10 @@ module StandardId
 
       def generate_token_response
         validate_audience!
-        enforce_audience_profile_binding!
+        StandardId::Instrumentation.instrument(
+          StandardId::Instrumentation::AUDIENCE_PROFILE_BINDING,
+          instrumentation_payload.merge(audience: Array(audience).reject(&:blank?))
+        ) { enforce_audience_profile_binding! }
         emit_token_issuing
         expires_in = token_expiry
         payload = build_jwt_payload(expires_in)

data/lib/standard_id/passwordless.rb

@@ -2,6 +2,12 @@ require "standard_id/passwordless/verification_service"
 
 module StandardId
   module Passwordless
+    # Last-resort per-challenge attempt ceiling, used only when neither
+    # :max_attempts_per_challenge nor :max_attempts is a positive number. NOT
+    # the default: with default config the ceiling is 3 (see
+    # .max_attempts_per_challenge).
+    FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE = 5
+
     class << self
       # Public API for verifying a passwordless OTP code.
       #
@@ -76,12 +82,18 @@ module StandardId
       # Resolve the per-challenge attempt ceiling, preferring the newer
       # :max_attempts_per_challenge setting but falling back to :max_attempts
       # for backwards compatibility with apps that configured the older name.
+      #
+      # With default config this resolves to 3 (:max_attempts' default).
+      # FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE applies only when BOTH settings are
+      # unset or non-positive (e.g. `max_attempts = 0` / nil) — a ceiling of
+      # zero would burn every challenge on its first wrong code, so it is never
+      # honoured.
       def max_attempts_per_challenge
         configured = StandardId.config.passwordless.max_attempts_per_challenge
         return configured.to_i if configured && configured.to_i.positive?
 
         legacy = StandardId.config.passwordless.max_attempts.to_i
-        legacy.positive? ? legacy : 5
+        legacy.positive? ? legacy : FALLBACK_MAX_ATTEMPTS_PER_CHALLENGE
       end
 
       # Minimum seconds that must elapse between successive code requests for

data/lib/standard_id/provider_registry.rb

@@ -5,6 +5,15 @@ module StandardId
     class ProviderNotFoundError < StandardError; end
     class InvalidProviderError < StandardError; end
 
+    # Keys a provider's `config_schema` entry may carry that belong to
+    # StandardId (see Providers::Base) rather than to ConfigSchema.
+    PROVIDER_FIELD_OPTIONS = %i[env required].freeze
+
+    # The gem-wide StandardId.deprecator (registered in
+    # Rails.application.deprecators), kept as a constant for existing callers.
+    # The Base.setup message names its own removal version (1.0).
+    DEPRECATOR = StandardId.deprecator
+
     @providers = Concurrent::Map.new
 
     class << self
@@ -19,7 +28,7 @@ module StandardId
         validate_provider!(provider_class)
         providers[name.to_s] = provider_class
         declare_config_schema(provider_class)
-        provider_class.setup if provider_class.respond_to?(:setup)
+        run_deprecated_setup(provider_class)
         provider_class
       end
 
@@ -84,10 +93,80 @@ module StandardId
         return if schema.nil? || schema.empty?
 
         schema.each do |field_name, options|
-          StandardId::ConfigSchema.add_field(scope: :social, name: field_name, **options)
+          field_options = options.except(*PROVIDER_FIELD_OPTIONS)
+          env_name = env_var_for(field_name, options)
+          field_options[:default] = env_default(env_name, options[:default]) if env_name
+
+          StandardId::ConfigSchema.add_field(scope: :social, name: field_name, **field_options)
         end
       end
 
+      # The ENV variable a provider config field falls back to, or nil.
+      #
+      # Canonical scheme: the upper-cased field name (`apple_private_key` →
+      # `APPLE_PRIVATE_KEY`). A provider overrides it per field with
+      # `env: "OTHER_NAME"`, or opts out with `env: false`.
+      #
+      # @param field_name [Symbol, String]
+      # @param options [Hash] the field's config_schema entry
+      # @return [String, nil]
+      def env_var_for(field_name, options = {})
+        env = options.fetch(:env, true)
+        return nil if env == false || env.nil?
+
+        env == true ? field_name.to_s.upcase : env.to_s
+      end
+
+      # Registered providers the host app has switched on (see
+      # Providers::Base.enabled?).
+      #
+      # @return [Hash{String => Class}] Provider name => class
+      def enabled
+        all.select { |_name, provider_class| provider_class.enabled? }
+      end
+
+      # Configuration problems across every registered provider.
+      #
+      # @return [Hash{String => Array<String>}] Provider name => errors, only
+      #   for providers that have any
+      def configuration_errors
+        all.each_with_object({}) do |(name, provider_class), errors|
+          provider_errors = provider_class.configuration_errors
+          errors[name] = provider_errors if provider_errors.any?
+        end
+      end
+
+      # Boot-time check that every enabled provider is fully configured.
+      #
+      # Run by StandardId::Engine once every plugin has registered. A provider
+      # whose client ID is set but whose other required fields are not starts
+      # its sign-in flow fine and only fails at the callback — after the user
+      # has already authenticated with the provider — so this surfaces it at
+      # boot instead.
+      #
+      # Behaviour follows `c.social.provider_misconfiguration`:
+      # - `:warn` (default) — log a warning in every environment.
+      # - `:raise` — raise StandardId::ConfigurationError in production; log a
+      #   warning in every other environment, so a developer without production
+      #   credentials can still boot the app.
+      #
+      # @param mode [Symbol] Override the configured mode
+      # @param logger [Logger, nil]
+      # @return [Hash{String => Array<String>}] the errors found
+      # @raise [StandardId::ConfigurationError]
+      def validate_configuration!(mode: StandardId.config.social.provider_misconfiguration, logger: StandardId.logger)
+        errors = configuration_errors
+        return errors if errors.empty?
+
+        message = "StandardId social provider configuration is incomplete: " +
+                  errors.map { |name, provider_errors| "#{name} (#{provider_errors.join('; ')})" }.join(", ")
+
+        raise StandardId::ConfigurationError, message if mode.to_s == "raise" && production?
+
+        logger&.warn("[StandardId] #{message}")
+        errors
+      end
+
       # Get provider by name
       # @param name [Symbol, String] Provider identifier
       # @return [Class] Provider class
@@ -114,6 +193,38 @@ module StandardId
 
       private
 
+      # A default that prefers a non-blank ENV value, then the field's own
+      # default. Evaluated lazily (ConfigSchema calls it when the config is
+      # built, or on first read of a field declared afterwards), and only when
+      # the host never assigned the field — an explicit assignment, even of
+      # nil, always wins.
+      def env_default(env_name, fallback)
+        lambda do
+          value = ENV[env_name]
+          next value if value.present?
+
+          fallback.respond_to?(:call) ? fallback.call : fallback
+        end
+      end
+
+      # Providers::Base.setup was removed in 0.42: no known plugin overrode
+      # it, and register — its only caller — runs from after_initialize, where
+      # a plugin's own Railtie can do the same work. A provider that still
+      # defines `setup` keeps working, with a deprecation warning.
+      def run_deprecated_setup(provider_class)
+        return unless provider_class.respond_to?(:setup)
+
+        DEPRECATOR.warn(
+          "#{provider_class.name || provider_class}.setup is deprecated and will not be called " \
+          "by StandardId 1.0. Move provider initialization into the plugin's Railtie."
+        )
+        provider_class.setup
+      end
+
+      def production?
+        defined?(Rails) && Rails.respond_to?(:env) && Rails.env.production?
+      end
+
       def validate_provider!(provider_class)
         unless provider_class.is_a?(Class)
           raise InvalidProviderError,

data/lib/standard_id/providers/base.rb

@@ -1,3 +1,6 @@
+require "uri"
+require "active_support/security_utils"
+
 module StandardId
   module Providers
     # Base class for social login providers.
@@ -225,17 +228,116 @@ module StandardId
           []
         end
 
-        # Optional setup hook called when provider is registered.
+        # --------------------------------------------------------------------
+        # Configuration & enablement
+        # --------------------------------------------------------------------
+        #
+        # Each entry returned by {config_schema} may carry two provider-level
+        # options in addition to the ConfigSchema ones (`type:`, `default:`).
+        # They are consumed by StandardId and never reach ConfigSchema:
+        #
+        # - `env:` — the ENV variable the field falls back to when the host app
+        #   never assigns it. Defaults to the upper-cased field name
+        #   (`google_client_id` → `GOOGLE_CLIENT_ID`), which is the canonical
+        #   naming scheme. Pass a String to use another variable, or `false` to
+        #   disable the ENV fallback for that field. Explicit configuration
+        #   (`c.social.google_client_id = ...`, including an explicit `nil`)
+        #   always wins over the ENV fallback.
+        # - `required: true` — the field must be present whenever the provider
+        #   is {enabled?}. Missing required fields are reported by
+        #   {configuration_errors} and by the boot-time check (see
+        #   `c.social.provider_misconfiguration`).
+        #
+        # Both options require standard_id >= 0.42. A plugin that declares them
+        # should depend on `standard_id >= 0.42` — older versions pass the
+        # options through to ConfigSchema and raise ArgumentError.
+        #
+        # @example
+        #   def self.config_schema
+        #     {
+        #       github_client_id: { type: :string, default: nil },
+        #       github_client_secret: { type: :string, default: nil, required: true },
+        #       github_enterprise_host: { type: :string, default: nil, env: false }
+        #     }
+        #   end
+
+        # Config field whose presence switches this provider on.
         #
-        # Override this method to perform initialization tasks like:
-        # - Registering additional routes
-        # - Adding custom validations
-        # - Setting up caching for JWKS
+        # Defaults to `:"<provider_name>_client_id"` when that field is part of
+        # {config_schema}, otherwise nil (a provider with no enabling field is
+        # always enabled once registered). Override when the provider keys off a
+        # different field.
         #
-        # @return [void]
+        # @return [Symbol, nil]
+        def enabling_config_field
+          field = :"#{provider_name}_client_id"
+          config_schema.key?(field) ? field : nil
+        end
+
+        # Config fields that must be present whenever the provider is enabled.
         #
-        def setup
-          # Override in subclasses if needed
+        # Defaults to the {config_schema} fields declared with `required: true`.
+        #
+        # @return [Array<Symbol>]
+        def required_config_fields
+          config_schema.select { |_name, options| options.is_a?(Hash) && options[:required] }.keys.map(&:to_sym)
+        end
+
+        # Whether the host app has switched this provider on.
+        #
+        # True when {enabling_config_field} is present in the configuration (or
+        # when the provider has no enabling field). Says nothing about whether
+        # the rest of the configuration is complete — see {configuration_errors}
+        # and {configured?}.
+        #
+        # @return [Boolean]
+        def enabled?
+          field = enabling_config_field
+          return true if field.nil?
+
+          config_value(field).present?
+        end
+
+        # Human-readable problems with this provider's configuration.
+        #
+        # Empty when the provider is disabled: a provider nobody switched on
+        # cannot be misconfigured. Messages name fields, never their values.
+        #
+        # @return [Array<String>]
+        def configuration_errors
+          return [] unless enabled?
+
+          missing = required_config_fields.select { |field| config_value(field).blank? }
+          return [] if missing.empty?
+
+          trigger = enabling_config_field ? " when #{enabling_config_field} is set" : ""
+          missing.map { |field| "#{field} is required#{trigger}" }
+        end
+
+        # Enabled and free of {configuration_errors}.
+        #
+        # @return [Boolean]
+        def configured?
+          enabled? && configuration_errors.empty?
+        end
+
+        # The flow a native/API callback is running, used as `context[:flow]`
+        # for {resolve_params}.
+        #
+        # Called by the API callback endpoint (`/api/oauth/callback/:provider`).
+        # The default honours an explicit `flow=web` param only for providers
+        # that {supports_mobile_callback?} — those are the providers whose web
+        # and native flows differ (e.g. Apple's distinct Services ID vs bundle
+        # ID audiences). Everything else is treated as `:mobile`, which is what
+        # the API endpoint served before this hook existed. Override to
+        # recognise other flows.
+        #
+        # @param params [#[]] Request params
+        # @return [Symbol] `:web` or `:mobile`
+        def flow_for(params)
+          return :mobile unless supports_mobile_callback?
+
+          params[:flow].to_s.downcase == "web" ? :web : :mobile
         end
 
         protected
@@ -252,6 +354,118 @@ module StandardId
             tokens: tokens.compact
           }.with_indifferent_access
         end
+
+        # Read one of this provider's config fields.
+        #
+        # Goes through the top-level `StandardId.config` accessor — the same
+        # way the provider plugins read their own credentials — so the value
+        # seen here always matches the one the provider will use.
+        #
+        # @param field [Symbol, String]
+        # @return [Object, nil]
+        def config_value(field)
+          StandardId.config.public_send(field)
+        end
+
+        # Run the block, re-raising any non-OAuth error as StandardId::OAuthError.
+        #
+        # StandardId::OAuthError (and subclasses such as InvalidRequestError)
+        # propagate unchanged. Anything else — network, JSON, OpenSSL, JWT
+        # errors — is wrapped so callers only ever handle OAuthError, with the
+        # original exception kept as `cause`.
+        #
+        # @param message_prefix [String, nil] Prepended to the wrapped error's
+        #   message, e.g. "Failed to fetch JWK" → "Failed to fetch JWK: <msg>"
+        # @return [Object] the block's return value
+        # @raise [StandardId::OAuthError]
+        #
+        # @example
+        #   def fetch_user_info(access_token:)
+        #     rescue_to_oauth_error do
+        #       response = HttpClient.get_with_bearer(USERINFO_ENDPOINT, access_token)
+        #       JSON.parse(response.body)
+        #     end
+        #   end
+        #
+        def rescue_to_oauth_error(message_prefix = nil)
+          yield
+        rescue StandardId::OAuthError
+          raise
+        rescue StandardError => e
+          message = message_prefix ? "#{message_prefix}: #{e.message}" : e.message
+          raise StandardId::OAuthError, message, cause: e
+        end
+
+        # Verify an ID token's `nonce` claim against the one the server issued.
+        #
+        # No-op when `expected` is blank (flows without a server-generated
+        # nonce). Comparison is constant-time. The error message deliberately
+        # does not include either nonce: the expected value is a server-side
+        # secret for the duration of the flow, and error messages end up in
+        # redirects, logs and error trackers.
+        #
+        # @param expected [String, nil] Nonce stored when the flow started
+        # @param actual [String, nil] `nonce` claim from the verified ID token
+        # @return [void]
+        # @raise [StandardId::InvalidRequestError] on mismatch
+        def verify_nonce!(expected:, actual:)
+          return if expected.blank?
+          return if actual.is_a?(String) && ActiveSupport::SecurityUtils.secure_compare(actual, expected.to_s)
+
+          raise StandardId::InvalidRequestError, "ID token nonce mismatch"
+        end
+
+        # Build an OAuth 2.0 authorization-code URL.
+        #
+        # Emits `client_id`, `redirect_uri`, `response_type`, `state`, then one
+        # entry per {supported_authorization_params}, taking the caller's value
+        # from `options` or falling back to `defaults`. Nil values are dropped.
+        #
+        # @param endpoint [String] Provider authorization endpoint
+        # @param client_id [String]
+        # @param redirect_uri [String]
+        # @param state [String]
+        # @param options [Hash] Caller-supplied authorization params
+        # @param defaults [Hash] Per-param fallbacks (e.g. `{ scope: "openid email" }`)
+        # @param response_type [String]
+        # @return [String]
+        #
+        # @example
+        #   def self.authorization_url(state:, redirect_uri:, **options)
+        #     build_authorization_url(
+        #       endpoint: AUTH_ENDPOINT,
+        #       client_id: StandardId.config.github_client_id,
+        #       redirect_uri:, state:, options:,
+        #       defaults: { scope: DEFAULT_SCOPE }
+        #     )
+        #   end
+        #
+        def build_authorization_url(endpoint:, client_id:, redirect_uri:, state:, options: {}, defaults: {}, response_type: "code")
+          query = {
+            client_id: client_id,
+            redirect_uri: redirect_uri,
+            response_type: response_type,
+            state: state
+          }
+
+          supported_authorization_params.each do |param|
+            query[param] = options[param] || defaults[param]
+          end
+
+          "#{endpoint}?#{URI.encode_www_form(query.compact)}"
+        end
+
+        # Pick the standard tokens out of a token-endpoint response.
+        #
+        # @param parsed_token [Hash] Parsed token response (String or Symbol keys)
+        # @return [Hash{Symbol => String}] `access_token`, `refresh_token` and
+        #   `id_token`, nil entries removed
+        def extract_tokens(parsed_token)
+          %i[access_token refresh_token id_token].each_with_object({}) do |key, tokens|
+            value = parsed_token[key.to_s] || parsed_token[key]
+            tokens[key] = value unless value.nil?
+          end
+        end
       end
     end
   end