token_authority 0.1.0 → 0.2.0

data/app/models/token_authority/client.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Represents an OAuth 2.1 client application.
+  #
+  # Clients can be either public (like mobile or SPA applications) or confidential
+  # (like server-side applications). Public clients use PKCE for security, while
+  # confidential clients can authenticate using client secrets or JWT assertions.
+  #
+  # This model handles client registration, authentication, and secure generation
+  # of client secrets using HMAC. Secrets are derived from a stored UUID rather
+  # than being stored directly, allowing secret rotation via the configuration's
+  # secret_key.
+  #
+  # @example Creating a public client (mobile app)
+  #   client = TokenAuthority::Client.create!(
+  #     name: "Mobile App",
+  #     redirect_uris: ["myapp://oauth/callback"],
+  #     token_endpoint_auth_method: "none"
+  #   )
+  #
+  # @example Creating a confidential client (server app)
+  #   client = TokenAuthority::Client.create!(
+  #     name: "Server App",
+  #     redirect_uris: ["https://app.example.com/oauth/callback"],
+  #     token_endpoint_auth_method: "client_secret_basic"
+  #   )
+  #   # Store client.client_secret securely
+  #
+  # @since 0.2.0
+  class Client < ApplicationRecord
+    CLIENT_TYPE_ENUM_VALUES = {public: "public", confidential: "confidential"}.freeze
+    SUPPORTED_AUTH_METHODS = %w[none client_secret_basic client_secret_post client_secret_jwt private_key_jwt].freeze
+
+    enum :client_type, CLIENT_TYPE_ENUM_VALUES, suffix: true
+
+    validates :name, presence: true, length: {minimum: 3, maximum: 255}
+    validates :access_token_duration, numericality: {only_integer: true, greater_than: 0}
+    validates :refresh_token_duration, numericality: {only_integer: true, greater_than: 0}
+    validates :redirect_uris, presence: true
+    validates :token_endpoint_auth_method, inclusion: {in: SUPPORTED_AUTH_METHODS}
+    validate :redirect_uris_are_valid_uris
+    validate :jwks_required_for_private_key_jwt
+
+    before_validation :set_default_durations, on: :create
+    before_validation :set_client_type_from_auth_method, on: :create
+    before_validation :set_default_grant_and_response_types, on: :create
+    before_create :generate_client_secret_id
+    before_create :generate_public_id
+    before_create :set_client_id_issued_at
+    before_create :set_client_secret_expiration
+
+    # Creates a new authorization grant for this client and the specified user.
+    #
+    # The grant represents the user's consent to allow this client access.
+    # PKCE challenge parameters should be included for public clients.
+    #
+    # @param user [User] the user granting authorization
+    # @param challenge_params [Hash] PKCE parameters (code_challenge, code_challenge_method)
+    #
+    # @return [TokenAuthority::AuthorizationGrant] the created authorization grant
+    #
+    # @example
+    #   grant = client.new_authorization_grant(
+    #     user: current_user,
+    #     challenge_params: {
+    #       code_challenge: "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM",
+    #       code_challenge_method: "S256"
+    #     }
+    #   )
+    def new_authorization_grant(user:, challenge_params: {})
+      TokenAuthority::AuthorizationGrant.create(token_authority_client: self, user:, **challenge_params)
+    end
+
+    # Creates a new authorization request object for validation.
+    #
+    # This service object validates all OAuth authorization parameters against
+    # the client's configuration and OAuth 2.1 requirements.
+    #
+    # @param client_id [String] the client identifier
+    # @param code_challenge [String] the PKCE code challenge
+    # @param code_challenge_method [String] the PKCE method (S256)
+    # @param redirect_uri [String] the callback URI
+    # @param response_type [String] the response type (code)
+    # @param state [String] the state parameter for CSRF protection
+    # @param resources [Array<String>] resource indicators (RFC 8707)
+    # @param scope [Array<String>] requested scopes
+    #
+    # @return [TokenAuthority::AuthorizationRequest] the validation object
+    def new_authorization_request(client_id:, code_challenge:, code_challenge_method:, redirect_uri:, response_type:, state:, resources: [], scope: [])
+      TokenAuthority::AuthorizationRequest.new(
+        token_authority_client: self,
+        client_id:,
+        state:,
+        code_challenge:,
+        code_challenge_method:,
+        redirect_uri:,
+        response_type:,
+        resources:,
+        scope:
+      )
+    end
+
+    # Builds a redirect URL with query parameters.
+    #
+    # Used to redirect back to the client application with authorization codes
+    # or error information.
+    #
+    # @param params [Hash] query parameters to append
+    #
+    # @return [String] the complete redirect URL
+    #
+    # @raise [TokenAuthority::InvalidRedirectUrlError] if the URI cannot be parsed
+    #
+    # @example
+    #   url = client.url_for_redirect(params: { code: "abc123", state: "xyz" })
+    def url_for_redirect(params:)
+      uri = URI(primary_redirect_uri)
+      params_for_query = params.collect { |key, value| [key.to_s, value] }
+      encoded_params = URI.encode_www_form(params_for_query)
+      uri.query = encoded_params
+      uri.to_s
+    rescue URI::InvalidURIError, ArgumentError, NoMethodError => error
+      raise TokenAuthority::InvalidRedirectUrlError, error.message
+    end
+
+    # Returns the client secret for confidential clients.
+    #
+    # The secret is derived from the client_secret_id using HMAC-SHA256 with
+    # the application's secret_key. This allows secret rotation by changing
+    # the secret_key without modifying the database.
+    #
+    # @return [String, nil] the client secret, or nil for public clients
+    #
+    # @note This secret should only be displayed once during client creation
+    #   and must be stored securely by the client application.
+    def client_secret
+      return nil if client_type == "public" || client_secret_id.blank?
+
+      generate_client_secret_for(client_secret_id)
+    end
+
+    # Authenticates a client using the provided secret.
+    #
+    # Uses constant-time comparison to prevent timing attacks that could be
+    # used to guess the client secret character by character.
+    #
+    # @param provided_secret [String] the secret to verify
+    #
+    # @return [Boolean] true if the secret is valid
+    #
+    # @example
+    #   if client.authenticate_with_secret(params[:client_secret])
+    #     # Client authenticated successfully
+    #   end
+    def authenticate_with_secret(provided_secret)
+      return false if client_type == "public" || client_secret_id.blank?
+      return false if provided_secret.blank?
+
+      # Use secure comparison to prevent timing attacks
+      ActiveSupport::SecurityUtils.secure_compare(
+        client_secret,
+        provided_secret
+      )
+    end
+
+    # Checks if a redirect URI is registered for this client.
+    #
+    # @param uri [String] the redirect URI to check
+    #
+    # @return [Boolean] true if the URI is registered
+    def redirect_uri_registered?(uri)
+      redirect_uris&.include?(uri)
+    end
+
+    # Returns the primary (first) redirect URI.
+    #
+    # Used as the default redirect URI when one is not explicitly specified
+    # by the client in the authorization request.
+    #
+    # @return [String, nil] the primary redirect URI
+    def primary_redirect_uri
+      redirect_uris&.first
+    end
+
+    # Indicates whether this is a URL-based client from a client metadata document.
+    #
+    # Always returns false for registered Client records. URL-based clients are
+    # represented by the ClientMetadataDocument class instead.
+    #
+    # @return [Boolean] false
+    #
+    # @see TokenAuthority::ClientMetadataDocument#url_based?
+    def url_based?
+      false
+    end
+
+    private
+
+    def redirect_uris_are_valid_uris
+      return if redirect_uris.blank?
+
+      redirect_uris.each do |uri|
+        parsed_uri = URI.parse(uri)
+        unless parsed_uri.is_a?(URI::HTTP) || parsed_uri.is_a?(URI::HTTPS)
+          errors.add(:redirect_uris, :invalid_http_scheme)
+          break
+        end
+      rescue URI::InvalidURIError
+        errors.add(:redirect_uris, :invalid_uri)
+        break
+      end
+    end
+
+    def jwks_required_for_private_key_jwt
+      return unless token_endpoint_auth_method == "private_key_jwt"
+      return if jwks.present? || jwks_uri.present?
+
+      errors.add(:base, :jwks_required_for_private_key_jwt)
+    end
+
+    def set_client_type_from_auth_method
+      return if client_type.present?
+
+      self.client_type = (token_endpoint_auth_method == "none") ? "public" : "confidential"
+    end
+
+    def set_default_grant_and_response_types
+      self.grant_types ||= ["authorization_code"]
+      self.response_types ||= ["code"]
+    end
+
+    def generate_client_secret_id
+      return if client_type == "public"
+
+      self.client_secret_id = SecureRandom.uuid
+    end
+
+    def generate_public_id
+      self.public_id = SecureRandom.uuid
+    end
+
+    def set_default_durations
+      self.access_token_duration ||= TokenAuthority.config.rfc_9068_default_access_token_duration
+      self.refresh_token_duration ||= TokenAuthority.config.rfc_9068_default_refresh_token_duration
+    end
+
+    def set_client_id_issued_at
+      self.client_id_issued_at = Time.current
+    end
+
+    def set_client_secret_expiration
+      return if client_type == "public"
+      return unless TokenAuthority.config.rfc_7591_client_secret_expiration
+
+      self.client_secret_expires_at = Time.current + TokenAuthority.config.rfc_7591_client_secret_expiration
+    end
+
+    def generate_client_secret_for(secret_id)
+      OpenSSL::HMAC.hexdigest("SHA256", TokenAuthority.config.secret_key, secret_id)
+    end
+  end
+end

data/app/models/token_authority/client_id_resolver.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  # Resolves a client_id to the appropriate client representation.
+  #
+  # This service object handles both traditional registered clients (identified by UUID)
+  # and URL-based clients that use client metadata documents per
+  # draft-ietf-oauth-client-id-metadata-document.
+  #
+  # The resolver determines which type of client is being used based on the format
+  # of the client_id:
+  # - HTTPS URLs are resolved as URL-based clients (fetching metadata documents)
+  # - UUIDs are resolved as registered clients (database lookups)
+  #
+  # URL-based client support can be disabled via configuration, in which case only
+  # registered clients are supported.
+  #
+  # @example Resolving a registered client
+  #   client = ClientIdResolver.resolve("550e8400-e29b-41d4-a716-446655440000")
+  #   client.class # => TokenAuthority::Client
+  #
+  # @example Resolving a URL-based client
+  #   client = ClientIdResolver.resolve("https://client.example.com/.well-known/oauth-client")
+  #   client.class # => TokenAuthority::ClientMetadataDocument
+  #
+  # @since 0.2.0
+  class ClientIdResolver
+    extend TokenAuthority::Instrumentation
+
+    class << self
+      # Resolves a client_id to either a Client or ClientMetadataDocument.
+      #
+      # Emits instrumentation events with the client type for monitoring.
+      #
+      # @param client_id [String] the client identifier (UUID or HTTPS URL)
+      #
+      # @return [TokenAuthority::Client, TokenAuthority::ClientMetadataDocument, nil]
+      #   the resolved client, or nil if client_id is blank
+      #
+      # @raise [TokenAuthority::ClientNotFoundError] if the client cannot be found
+      #   or the metadata document cannot be fetched
+      #
+      # @example
+      #   client = ClientIdResolver.resolve(params[:client_id])
+      #   if client.public_client_type?
+      #     # Handle public client
+      #   end
+      def resolve(client_id)
+        instrument("client.resolve") do |payload|
+          return nil if client_id.blank?
+
+          # Check if it's a URL-based client_id
+          if url_based_client_id?(client_id)
+            payload[:client_type] = "url_based"
+            resolve_url_based(client_id)
+          else
+            payload[:client_type] = "registered"
+            resolve_uuid_based(client_id)
+          end
+        end
+      end
+
+      # Checks if a client_id represents a URL-based client.
+      #
+      # URL-based clients are identified by HTTPS URLs and are only supported
+      # when client_metadata_document_enabled is true in the configuration.
+      #
+      # @param client_id [String] the client identifier to check
+      #
+      # @return [Boolean] true if this is a URL-based client_id
+      def url_based_client_id?(client_id)
+        return false if client_id.blank?
+        return false unless TokenAuthority.config.client_metadata_document_enabled
+
+        # Check if it looks like a URL
+        client_id.start_with?("https://")
+      end
+
+      private
+
+      # Resolves a URL-based client by fetching its metadata document.
+      #
+      # @param client_id [String] the HTTPS URL of the client
+      #
+      # @return [TokenAuthority::ClientMetadataDocument] the metadata document
+      #
+      # @raise [TokenAuthority::ClientNotFoundError] if fetching or parsing fails
+      # @api private
+      def resolve_url_based(client_id)
+        # Validate and fetch the metadata document
+        metadata = ClientMetadataDocumentFetcher.fetch(client_id)
+        ClientMetadataDocument.new(metadata)
+      rescue InvalidClientMetadataDocumentUrlError, ClientMetadataDocumentFetchError, InvalidClientMetadataDocumentError
+        # If URL-based resolution fails, raise ClientNotFoundError for consistent error handling
+        raise ClientNotFoundError
+      end
+
+      # Resolves a UUID-based registered client from the database.
+      #
+      # @param client_id [String] the UUID of the client
+      #
+      # @return [TokenAuthority::Client] the registered client
+      #
+      # @raise [TokenAuthority::ClientNotFoundError] if no client is found
+      # @api private
+      def resolve_uuid_based(client_id)
+        client = TokenAuthority::Client.find_by(public_id: client_id)
+        raise ClientNotFoundError if client.nil?
+
+        client
+      end
+    end
+  end
+end

data/app/models/token_authority/client_metadata_document.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  ##
+  # Represents a client identified by a URL-based client_id (Client Metadata Document spec).
+  # Implements the same interface as Client for use in OAuth flows.
+  class ClientMetadataDocument
+    attr_reader :metadata
+
+    def initialize(metadata)
+      @metadata = metadata.with_indifferent_access
+    end
+
+    # The client_id is the URL itself
+    def public_id
+      metadata[:client_id]
+    end
+
+    # URL-based clients are always public (per spec)
+    def client_type
+      "public"
+    end
+
+    def public_client_type?
+      true
+    end
+
+    def confidential_client_type?
+      false
+    end
+
+    def name
+      metadata[:client_name] || metadata[:client_id]
+    end
+
+    def redirect_uris
+      metadata[:redirect_uris] || []
+    end
+
+    def redirect_uri_registered?(uri)
+      redirect_uris.include?(uri)
+    end
+
+    def primary_redirect_uri
+      redirect_uris.first
+    end
+
+    # URL-based clients use default token durations from config
+    def access_token_duration
+      TokenAuthority.config.rfc_9068_default_access_token_duration
+    end
+
+    def refresh_token_duration
+      TokenAuthority.config.rfc_9068_default_refresh_token_duration
+    end
+
+    # URL-based clients cannot have secrets
+    def client_secret
+      nil
+    end
+
+    def client_secret_id
+      nil
+    end
+
+    def authenticate_with_secret(_provided_secret)
+      false
+    end
+
+    # URL-based clients always use "none" for token endpoint auth
+    def token_endpoint_auth_method
+      "none"
+    end
+
+    def grant_types
+      metadata[:grant_types] || ["authorization_code"]
+    end
+
+    def response_types
+      metadata[:response_types] || ["code"]
+    end
+
+    def scope
+      metadata[:scope]
+    end
+
+    # Human-readable metadata
+    def client_uri
+      metadata[:client_uri]
+    end
+
+    def logo_uri
+      metadata[:logo_uri]
+    end
+
+    def tos_uri
+      metadata[:tos_uri]
+    end
+
+    def policy_uri
+      metadata[:policy_uri]
+    end
+
+    def contacts
+      metadata[:contacts]
+    end
+
+    # Technical metadata
+    def jwks_uri
+      metadata[:jwks_uri]
+    end
+
+    def jwks
+      metadata[:jwks]
+    end
+
+    def software_id
+      metadata[:software_id]
+    end
+
+    def software_version
+      metadata[:software_version]
+    end
+
+    # Creates a new authorization grant for this URL-based client
+    def new_authorization_grant(user:, challenge_params: {})
+      TokenAuthority::AuthorizationGrant.create(
+        client_id_url: public_id,
+        user:,
+        **challenge_params
+      )
+    end
+
+    # Creates a new authorization request for this URL-based client
+    def new_authorization_request(client_id:, code_challenge:, code_challenge_method:, redirect_uri:, response_type:, state:, resources: [], scope: [])
+      TokenAuthority::AuthorizationRequest.new(
+        token_authority_client: self,
+        client_id:,
+        state:,
+        code_challenge:,
+        code_challenge_method:,
+        redirect_uri:,
+        response_type:,
+        resources:,
+        scope:
+      )
+    end
+
+    def url_for_redirect(params:)
+      uri = URI(primary_redirect_uri)
+      params_for_query = params.collect { |key, value| [key.to_s, value] }
+      encoded_params = URI.encode_www_form(params_for_query)
+      uri.query = encoded_params
+      uri.to_s
+    rescue URI::InvalidURIError, ArgumentError, NoMethodError => error
+      raise TokenAuthority::InvalidRedirectUrlError, error.message
+    end
+
+    # Check if this is a URL-based client (always true for this class)
+    def url_based?
+      true
+    end
+  end
+end

data/app/models/token_authority/client_metadata_document_cache.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  ##
+  # Stores cached client metadata documents fetched from remote URIs
+  class ClientMetadataDocumentCache < ApplicationRecord
+    validates :uri_hash, presence: true, uniqueness: true
+    validates :uri, presence: true
+    validates :metadata, presence: true
+    validates :expires_at, presence: true
+
+    scope :expired, -> { where("expires_at <= ?", Time.current) }
+    scope :valid, -> { where("expires_at > ?", Time.current) }
+
+    class << self
+      def find_by_uri(uri)
+        find_by(uri_hash: hash_uri(uri))
+      end
+
+      def hash_uri(uri)
+        Digest::SHA256.hexdigest(uri)
+      end
+
+      def cleanup_expired!
+        expired.delete_all
+      end
+    end
+
+    def expired?
+      expires_at <= Time.current
+    end
+  end
+end