authproto 0.3.0.beta1

data/lib/authproto/token/refresh.rb

@@ -0,0 +1,414 @@
+# frozen_string_literal: true
+
+require 'jose'
+require 'json'
+require 'monitor'
+
+require_relative '../configuration'
+require_relative '../errors'
+require_relative '../http_client'
+require_relative '../par'
+require_relative '../par/client_assertion'
+require_relative '../state/token_set'
+
+module AuthProto
+
+  #
+  # Token error types and synchronized refresh-token exchange operations.
+  #
+
+  module Token
+
+    #
+    # Base error class for token-related errors
+    #
+
+    class Error < AuthProto::Error
+
+      # Kind of token associated with the failure.
+      # @return [String]
+      attr_reader :token_type
+
+      # Machine-readable token error code.
+      # @return [String]
+      attr_reader :error_code
+
+      # Whether retrying the operation may succeed.
+      # @return [Boolean]
+      attr_reader :retry_possible
+
+      # Creates a token error with structured retry information.
+      #
+      # @param message [String] human-readable failure description
+      # @param token_type [String] kind of token associated with the failure
+      # @param error_code [String] machine-readable failure code
+      # @param retry_possible [Boolean] whether retrying may succeed
+      #
+      def initialize(message, token_type:, error_code:, retry_possible: false)
+        @token_type = token_type
+        @error_code = error_code
+        @retry_possible = retry_possible
+        super(message)
+      end
+    end
+
+    #
+    # Raised for token expiry; its retry metadata permits a refresh/retry.
+    #
+
+    class ExpiredTokenError < Error
+
+      # Creates an error describing token expiry.
+      # @param token_type [String] kind of token that failed
+      #
+      def initialize(token_type:)
+        super(
+          "Token has expired",
+          token_type: token_type,
+          error_code: "token_expired",
+          retry_possible: true
+        )
+      end
+    end
+
+    #
+    # Raised when a token is structurally valid but has been invalidated or revoked
+    #
+
+    class InvalidTokenError < Error
+
+      # Creates an error describing token invalidation/revocation.
+      # @param token_type [String] kind of token that failed
+      #
+      def initialize(token_type:)
+        super(
+          "Token is invalid",
+          token_type: token_type,
+          error_code: "token_invalid",
+          retry_possible: false
+        )
+      end
+    end
+
+    #
+    # Raised during token refresh operations, includes retry information and server responses
+    #
+
+    class RefreshError < Error
+
+      # Creates a refresh error with retry metadata.
+      #
+      # @param message [String] failure description
+      # @param retry_possible [Boolean] whether a later retry may succeed
+      #
+      def initialize(message, retry_possible: true)
+        super(
+          message,
+          token_type: "refresh",
+          error_code: "refresh_failed",
+          retry_possible: retry_possible
+        )
+      end
+    end
+
+    #
+    # Handles token refresh operations with retry logic
+    #
+
+    class Refresh
+      include MonitorMixin
+
+      # Maximum attempts for one refresh operation.
+      # @return [Integer]
+      MAX_RETRIES = 3
+
+      # Initial retry delay in seconds before jitter.
+      # @return [Integer]
+      BASE_DELAY = 1
+
+      # Maximum retry delay in seconds before jitter.
+      # @return [Integer]
+      MAX_DELAY = 8
+
+      # Session containing the tokens to refresh.
+      # @return [State::Session]
+      attr_reader :session
+
+      # DPoP client used to sign refresh requests.
+      # @return [DPoP::Client]
+      attr_reader :dpop_client
+
+      # Server providing the token endpoint.
+      # @return [ServerMetadata::AuthorizationServer]
+      attr_reader :auth_server
+
+      # Client metadata used for optional confidential-client assertions.
+      # @return [ClientMetadata]
+      attr_reader :client_metadata
+
+      # Creates a synchronized refresh operation for an existing OAuth session.
+      #
+      # @param session [State::Session] session with an access and refresh token
+      # @param dpop_client [DPoP::Client] proof signer and nonce tracker
+      # @param auth_server [ServerMetadata::AuthorizationServer] server with a token endpoint
+      # @param client_metadata [ClientMetadata] client ID and authentication key configuration
+      #
+      def initialize(session:, dpop_client:, auth_server:, client_metadata:)
+        super() # Initialize MonitorMixin
+        @session = session
+        @dpop_client = dpop_client
+        @auth_server = auth_server
+        @attempt_count = 0
+        @client_metadata = client_metadata
+      end
+
+      # Exchanges a refresh token for a replacement token set.
+      #
+      # Retries eligible failures up to {MAX_RETRIES} times with exponential backoff and
+      # jitter, and handles a DPoP nonce challenge during token exchange. Does not assign
+      # the returned tokens to the session or persist them; the caller must do so.
+      #
+      # @return [State::TokenSet] validated replacement tokens
+      # @raise [RefreshError] if the session is not renewable, refresh fails, or retries are exhausted
+      #
+      def perform
+        synchronize do
+          raise RefreshError.new("No refresh token available", retry_possible: false) unless session.renewable?
+          raise RefreshError.new("No access token to refresh", retry_possible: false) if session.tokens.nil?
+
+          with_retries do
+            request_token_refresh
+          end
+        end
+      end
+
+
+      private
+
+      def with_retries
+        @attempt_count = 0
+        last_error = nil
+
+        while @attempt_count < MAX_RETRIES
+          begin
+            return yield
+          rescue RefreshError, HTTPClient::HTTPError => e
+            last_error = e
+            @attempt_count += 1
+
+            # Don't retry if error indicates retry not possible
+            raise e if e.respond_to?(:retry_possible) && !e.retry_possible
+
+            sleep calculate_delay if @attempt_count < MAX_RETRIES
+          end
+        end
+
+        # Reached max retries
+        raise RefreshError.new(
+          "Token refresh failed after #{MAX_RETRIES} attempts: #{last_error.message}",
+          retry_possible: false
+        )
+      end
+
+      def calculate_delay
+        # Exponential backoff with jitter
+        delay = [BASE_DELAY * (2**(@attempt_count - 1)), MAX_DELAY].min
+        delay + (rand * 0.5 * delay) # Add up to 50% jitter
+      end
+
+      def request_token_refresh
+        # Initial token request without nonce
+        response = make_token_request(session)
+
+        # Handle DPoP nonce requirement
+        if requires_dpop_nonce?(response)
+          # Extract and store nonce from error response
+          extract_dpop_nonce(response)
+          dpop_client.process_response(response[:headers], auth_server.issuer)
+
+          # Retry request with nonce
+          response = make_token_request(session)
+        end
+
+        handle_refresh_response(response)
+      end
+
+      def make_token_request(session)
+        # Generate proof
+        proof = dpop_client.generate_proof(
+          http_method: "POST",
+          http_uri: auth_server.token_endpoint
+        )
+
+        body = {
+          grant_type: "refresh_token",
+          refresh_token: session.tokens.refresh_token,
+          scope: session.scope,
+          client_id: client_metadata.client_id
+        }
+
+        # Add client authentication if available
+        add_client_authentication(body) if client_metadata.confidential?
+
+        AuthProto.configuration.http_client.post(
+          auth_server.token_endpoint,
+          body: body,
+          headers: {
+            "Content-Type" => "application/x-www-form-urlencoded",
+            "DPoP" => proof
+          }
+        )
+      end
+
+      def requires_dpop_nonce?(response)
+        return false unless response[:status] == 400
+        return false if response[:body].nil?
+
+        error_data = JSON.parse(response[:body])
+        error_data.is_a?(Hash) && error_data["error"] == "use_dpop_nonce"
+      rescue JSON::ParserError
+        false
+      end
+
+      def extract_dpop_nonce(response)
+        nonce = (response[:headers] || {}).detect { |k, v| k.downcase == "dpop-nonce" }&.last
+
+        unless nonce.is_a?(String) && !nonce.empty?
+          raise RefreshError.new("No DPoP nonce provided in error response", retry_possible: false)
+        end
+
+        nonce
+      end
+
+      def add_client_authentication(body)
+        return unless client_metadata.jwks && !client_metadata.jwks["keys"].empty?
+
+        signing_key = JOSE::JWK.from_map(client_metadata.jwks["keys"].first)
+        client_assertion = PAR::ClientAssertion.new(
+          client_id: client_metadata.client_id,
+          signing_key: signing_key
+        )
+
+        body.merge!(
+          client_assertion_type: PAR::CLIENT_ASSERTION_TYPE,
+          client_assertion: client_assertion.generate_jwt(
+            audience: auth_server.issuer
+          )
+        )
+      end
+
+      def handle_refresh_response(response)
+        case response[:status]
+        when 200
+          process_successful_response(response)
+        when 400
+          handle_400_response(response)
+        when 401
+          raise RefreshError.new("Refresh token is invalid", retry_possible: false)
+        when 429
+          handle_rate_limit_response(response)
+        else
+          raise RefreshError, "Unexpected response: #{response[:status]}"
+        end
+      end
+
+      def process_successful_response(response)
+        raise RefreshError.new("Missing response body", retry_possible: false) if response[:body].nil?
+
+        data = JSON.parse(response[:body])
+        validate_refresh_response(data)
+
+        AuthProto::State::TokenSet.new(
+          access_token: data["access_token"],
+          token_type: data["token_type"],
+          expires_in: data["expires_in"],
+          refresh_token: data["refresh_token"],
+          scope: data["scope"],
+          sub: data["sub"]
+        )
+      rescue JSON::ParserError => e
+        raise RefreshError.new("Invalid response format: #{e.message}", retry_possible: false)
+      end
+
+      def handle_400_response(response)
+        raise RefreshError.new("Missing error response body", retry_possible: false) if response[:body].nil?
+
+        error_data = JSON.parse(response[:body])
+
+        unless error_data.is_a?(Hash)
+          raise RefreshError.new("Invalid error response format", retry_possible: false)
+        end
+
+        error_description = error_data["error_description"] || error_data["error"]
+
+        case error_data["error"]
+        when "use_dpop_nonce"
+          extract_dpop_nonce(response)
+          dpop_client.process_response(response[:headers], auth_server.issuer)
+          raise RefreshError.new("Retry with DPoP nonce", retry_possible: true)
+        when "invalid_grant"
+          # The refresh token has been invalidated or already used
+          raise RefreshError.new(
+            "Refresh token has been invalidated: #{error_description}",
+            retry_possible: false
+          )
+        else
+          raise RefreshError.new(
+            "Refresh request failed: #{error_description}",
+            retry_possible: false
+          )
+        end
+      rescue JSON::ParserError
+        raise RefreshError.new("Invalid error response format", retry_possible: false)
+      end
+
+      def handle_rate_limit_response(response)
+        # Extract retry-after if available
+        retry_after = response[:headers]["Retry-After"]&.to_i || calculate_delay
+        raise RefreshError, "Rate limited - retry after #{retry_after} seconds"
+      end
+
+      def validate_refresh_response(data)
+        unless data.is_a?(Hash)
+          raise RefreshError.new("Token response must be a JSON object", retry_possible: false)
+        end
+
+        # Required fields
+        %w[access_token token_type expires_in scope sub].each do |field|
+          raise RefreshError.new("Missing #{field} in response", retry_possible: false) unless data[field]
+        end
+
+        %w[access_token token_type scope sub].each do |field|
+          unless data[field].is_a?(String) && !data[field].empty?
+            raise RefreshError.new("Invalid #{field} in response", retry_possible: false)
+          end
+        end
+
+        unless data["expires_in"].is_a?(Integer)
+          raise RefreshError.new("Invalid expires_in in response", retry_possible: false)
+        end
+
+        unless data["refresh_token"].nil? || data["refresh_token"].is_a?(String)
+          raise RefreshError.new("Invalid refresh_token in response", retry_possible: false)
+        end
+
+        # Token type must be DPoP
+        unless data["token_type"] == "DPoP"
+          raise RefreshError.new("Invalid token_type: #{data["token_type"]}", retry_possible: false)
+        end
+
+        # Scope must include original scopes
+        original_scopes = session.scope.split
+        response_scopes = data["scope"].split
+        unless (original_scopes - response_scopes).empty?
+          raise RefreshError.new("Invalid scope in response", retry_possible: false)
+        end
+
+        # Subject must match
+        return if data["sub"] == session.tokens.sub
+
+        raise RefreshError.new("Subject mismatch in response", retry_possible: false)
+      end
+    end
+  end
+end

data/lib/authproto/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module AuthProto
+
+  # Current gem version.
+  # @return [String]
+  VERSION = "0.3.0.beta1"
+end

data/lib/authproto.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative 'authproto/client'
+require_relative 'authproto/configuration'
+require_relative 'authproto/http_client'
+require_relative 'authproto/insecure_http_client'
+require_relative 'authproto/localhost_server'
+require_relative 'authproto/serialization/dpop_key'
+require_relative 'authproto/version'
+
+#
+# AuthProto is a Ruby library implementing the AT Protocol OAuth specification.
+# It provides OAuth clients with DPoP, PAR, identity discovery, client metadata
+# validation, and storage for sessions and tokens.
+#
+
+module AuthProto
+end

data/sig/authproto/client.rbs

@@ -0,0 +1,43 @@
+module AuthProto
+  class Client
+    class CallbackError < AuthProto::Error
+    end
+    class TokenError < AuthProto::Error
+    end
+    class SessionError < AuthProto::Error
+      attr_reader session_id: String?
+      def initialize: (String message, ?session_id: String?) -> void
+    end
+
+    attr_reader client_id: String
+    attr_reader redirect_uri: String
+    attr_reader client_metadata: ClientMetadata
+    attr_reader session_manager: State::SessionManager
+    attr_reader dpop_client: DPoP::Client
+
+    def initialize: (client_id: String, redirect_uri: String, ?metadata: json_object?, ?dpop_key: (json_object | JOSE::Map)?) -> void
+    def authorize: (?handle: String?, ?pds_url: String?, ?scope: String) -> authorization_result
+    def handle_callback: (code: String, state: String, iss: String) -> callback_result
+    def get_tokens: (String session_id) -> token_info?
+    def refresh_token: (String session_id) -> refreshed_tokens
+    def authorized?: (String session_id) -> bool
+    def auth_headers: (session_id: String, method: String, url: String) -> Hash[String, String]
+    def remove_session: (String session_id) -> void
+    def cleanup_expired_sessions: () -> void
+
+    private
+    def load_client_metadata: (json_object? metadata) -> ClientMetadata
+    def validate_redirect_uri: () -> void
+    def initialize_dpop: ((json_object | JOSE::Map)? key) -> DPoP::Client
+    def validate_auth_params!: (String? handle, String? pds_url, String scope) -> void
+    def resolve_from_handle: (String handle, State::Session session) -> { server: ServerMetadata::AuthorizationServer, pds: String }
+    def resolve_from_pds: (String pds_url, State::Session session) -> { server: ServerMetadata::AuthorizationServer, pds: String }
+    def resolve_auth_server: (String pds_url) -> ServerMetadata::AuthorizationServer
+    def generate_authorization_url: (ServerMetadata::AuthorizationServer auth_server, State::Session session, ?login_hint: String?) -> String
+    def exchange_code: (code: String, session: State::Session) -> json_object
+    def make_token_request: (String code, State::Session session) -> http_response
+    def requires_dpop_nonce?: (http_response response) -> bool
+    def extract_dpop_nonce: (http_response response) -> String
+    def validate_token_response: (json_object response, State::Session session) -> void
+  end
+end

data/sig/authproto/client_metadata.rbs

@@ -0,0 +1,113 @@
+module AuthProto
+  # Handles and validates AT Protocol OAuth client metadata.
+  class ClientMetadata
+    AUTH_PRIVATE_KEY_JWT: String
+    SCOPE_PATTERN: Regexp
+
+    @client_id: String
+
+    @grant_types: Array[String]
+
+    @response_types: Array[String]
+
+    @redirect_uris: Array[String]
+
+    @scope: String
+
+    @client_name: String?
+
+    @application_type: String
+
+    @client_uri: String?
+
+    @logo_uri: String?
+
+    @tos_uri: String?
+
+    @policy_uri: String?
+
+    @token_endpoint_auth_method: String
+
+    @token_endpoint_auth_signing_alg: String?
+
+    @jwks: Hash[String, untyped]?
+
+    @jwks_uri: String?
+
+    attr_reader client_id: String
+    attr_reader grant_types: Array[String]
+    attr_reader response_types: Array[String]
+    attr_reader redirect_uris: Array[String]
+    attr_reader scope: String
+    attr_reader client_name: String?
+    attr_reader client_uri: String?
+    attr_reader logo_uri: String?
+    attr_reader tos_uri: String?
+    attr_reader policy_uri: String?
+    attr_reader token_endpoint_auth_method: String
+    attr_reader jwks: Hash[String, untyped]?
+    attr_reader jwks_uri: String?
+    attr_reader application_type: String
+
+    def initialize: (Hash[String, untyped] metadata) -> void
+
+    def self.from_url: (String url) -> ClientMetadata
+
+    def confidential?: () -> bool
+
+    private
+
+    def validate_and_set_metadata: (Hash[String, untyped] metadata) -> void
+
+    def validate_client_id: (String client_id) -> String
+
+    def valid_https_client_id?: (String client_id) -> bool
+
+    def valid_localhost_client_id?: (String client_id) -> bool
+
+    def validate_grant_types: (Array[String] grant_types) -> Array[String]
+
+    def validate_response_types: (Array[String] response_types) -> Array[String]
+
+    def validate_redirect_uris: (Array[String] uris) -> Array[String]
+
+    def validate_redirect_uri: (String value) -> void
+
+    def validate_https_redirect_uri: (URI::Generic uri, String? port) -> void
+
+    def validate_redirect_uri_origin: (URI::Generic uri) -> void
+
+    def validate_native_redirect_uri: (URI::Generic uri, String? port) -> void
+
+    def validate_custom_scheme: (URI::Generic uri) -> void
+
+    def validate_scope: (String scope) -> String
+
+    def validate_application_type: (String? type) -> String
+
+    def validate_client_name: (String? name) -> String?
+
+    def validate_client_uri: (String? uri) -> String?
+
+    def validate_https_uri: (String? uri) -> String?
+
+    def validate_jwks: (Hash[String, untyped] jwks) -> void
+
+    def validate_auth_methods: (Hash[String, untyped] metadata) -> void
+
+    def validate_auth_public: (Hash[String, untyped] metadata) -> void
+
+    def validate_auth_confidential: (Hash[String, untyped] metadata) -> void
+
+    def validate_dpop: (Hash[String, untyped] metadata) -> void
+
+  end
+end
+
+module AuthProto
+  module ApplicationType
+    WEB: String
+    NATIVE: String
+    ALL: Array[String]
+  end
+end

data/sig/authproto/dependencies.rbs

@@ -0,0 +1,19 @@
+# Minimal nominal types for the JOSE objects exposed by AuthProto's API.
+# JOSE currently ships no RBS; this is not a signature for its complete API.
+module JOSE
+  class Map
+    def []: (String key) -> untyped
+    def to_h: () -> Hash[String, untyped]
+  end
+
+  class SignedBinary < String
+  end
+
+  class JWK
+    attr_accessor fields: Map
+    def self.from_map: (Hash[String, untyped] | Map jwk, ?untyped modules, ?untyped key) -> JWK
+    def self.generate_key: (untyped params) -> JWK
+    def to_map: (?untyped key, ?untyped jwe) -> Map
+    def to_public: () -> JWK
+  end
+end

data/sig/authproto/dpop/client.rbs

@@ -0,0 +1,23 @@
+module AuthProto
+  module DPoP
+    class Client
+      class Error < AuthProto::Error
+      end
+
+      attr_reader key_manager: KeyManager
+      attr_reader proof_generator: ProofGenerator
+      attr_reader nonce_manager: NonceManager
+
+      def initialize: (?key_manager: KeyManager?, ?nonce_ttl: Integer?) -> void
+      def generate_proof: (http_method: String, http_uri: String, ?access_token: String?, ?nonce: String?) -> JOSE::SignedBinary
+      def process_response: (Hash[String, String]? response_headers, String server_url) -> void
+      def request_headers: (String proof) -> { "DPoP" => String }
+      def public_key: () -> json_object
+      def export_key: (?include_private: bool) -> JOSE::Map
+
+      private
+      def extract_nonce: (Hash[String | Symbol, String] headers) -> String?
+      def origin_for_uri: (URI::HTTP uri) -> String
+    end
+  end
+end

data/sig/authproto/dpop/key_manager.rbs

@@ -0,0 +1,26 @@
+module AuthProto
+  module DPoP
+    class KeyManager
+      class KeyError < AuthProto::Error
+      end
+
+      CURVE: String
+      ALGORITHM: String
+      attr_reader keypair: JOSE::JWK
+
+      def initialize: (?JOSE::JWK? keypair) -> void
+      def generate_keypair: () -> JOSE::JWK
+      def public_jwk: () -> json_object
+      def sign: (String data) -> JOSE::SignedBinary
+      def sign_segments: (Hash[String | Symbol, untyped] header, Hash[String | Symbol, untyped] payload) -> JOSE::SignedBinary
+      def deep_stringify_keys: (untyped obj) -> untyped
+      def verify: (String signed_jws) -> bool
+      def to_jwk: (?include_private: bool) -> JOSE::Map
+      def self.from_jwk: (json_object | JOSE::Map jwk) -> KeyManager
+
+      private
+      def generate_kid: (json_object | JOSE::Map jwk) -> String
+      def validate_keypair: () -> void
+    end
+  end
+end

data/sig/authproto/dpop/nonce_manager.rbs

@@ -0,0 +1,23 @@
+module AuthProto
+  module DPoP
+    class NonceManager
+      @ttl: Integer
+      @serializer: Serialization::StoredNonce
+
+      class NonceError < AuthProto::Error
+      end
+
+      DEFAULT_TTL: Integer
+      def initialize: (?ttl: Integer?) -> void
+      def update: (nonce: String, server_url: String) -> void
+      def get: (String server_url) -> String?
+      def clear: (String server_url) -> bool
+      def valid_nonce?: (String server_url) -> bool
+
+      private
+      def normalize_server_url: (String url) -> String
+      def validate_inputs: (String nonce, String server_url) -> void
+      def validate_server_url: (String server_url) -> void
+    end
+  end
+end