token_authority 0.1.0 → 0.2.0

data/app/models/token_authority/client_metadata_document_fetcher.rb

@@ -0,0 +1,266 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "resolv"
+require "ipaddr"
+
+module TokenAuthority
+  ##
+  # Service for fetching and caching client metadata documents from remote URIs
+  class ClientMetadataDocumentFetcher
+    extend TokenAuthority::Instrumentation
+    include TokenAuthority::EventLogging
+
+    # Private IP ranges for SSRF protection
+    PRIVATE_IP_RANGES = [
+      IPAddr.new("10.0.0.0/8"),
+      IPAddr.new("172.16.0.0/12"),
+      IPAddr.new("192.168.0.0/16"),
+      IPAddr.new("127.0.0.0/8"),
+      IPAddr.new("169.254.0.0/16"),  # Link-local
+      IPAddr.new("0.0.0.0/8"),
+      IPAddr.new("::1/128"),          # IPv6 localhost
+      IPAddr.new("fc00::/7"),         # IPv6 unique local
+      IPAddr.new("fe80::/10")         # IPv6 link-local
+    ].freeze
+
+    class << self
+      def fetch(uri)
+        instrument("client_metadata.fetch", uri: uri) do |payload|
+          validate_url!(uri)
+
+          cached = ClientMetadataDocumentCache.find_by_uri(uri)
+
+          if cached && !cached.expired?
+            debug_event("client.metadata.cache_hit", uri: uri, expires_at: cached.expires_at&.iso8601)
+            payload[:cache_hit] = true
+            return cached.metadata
+          end
+
+          debug_event("client.metadata.cache_miss", uri: uri)
+          payload[:cache_hit] = false
+
+          # Fetch fresh data and update/create cache entry
+          metadata = fetch_from_uri(uri)
+          validate_metadata!(uri, metadata)
+          store_in_cache(uri, metadata)
+
+          debug_event("client.metadata.fetched", uri: uri, client_name: metadata["client_name"])
+
+          metadata
+        end
+      end
+
+      def clear_cache(uri)
+        ClientMetadataDocumentCache.find_by_uri(uri)&.destroy
+      end
+
+      def cleanup_expired!
+        ClientMetadataDocumentCache.cleanup_expired!
+      end
+
+      def valid_client_id_url?(url)
+        validate_url!(url)
+        true
+      rescue InvalidClientMetadataDocumentUrlError
+        false
+      end
+
+      private
+
+      def validate_url!(url)
+        parsed_uri = URI.parse(url)
+
+        # Must be HTTPS
+        unless parsed_uri.is_a?(URI::HTTPS)
+          raise InvalidClientMetadataDocumentUrlError, "Client ID URL must use HTTPS scheme"
+        end
+
+        # Must have a path (not just "/")
+        if parsed_uri.path.blank? || parsed_uri.path == "/"
+          raise InvalidClientMetadataDocumentUrlError, "Client ID URL must have a path"
+        end
+
+        # Must not have a fragment
+        if parsed_uri.fragment.present?
+          raise InvalidClientMetadataDocumentUrlError, "Client ID URL must not have a fragment"
+        end
+
+        # Must not have user credentials
+        if parsed_uri.user.present? || parsed_uri.password.present?
+          raise InvalidClientMetadataDocumentUrlError, "Client ID URL must not have credentials"
+        end
+
+        # Check host against allow/block lists
+        validate_host!(parsed_uri.host)
+
+        true
+      rescue URI::InvalidURIError => e
+        raise InvalidClientMetadataDocumentUrlError, "Invalid URI: #{e.message}"
+      end
+
+      def validate_host!(host)
+        config = TokenAuthority.config
+
+        # Check blocked hosts
+        if config.client_metadata_document_blocked_hosts&.any? { |pattern| host_matches?(host, pattern) }
+          raise InvalidClientMetadataDocumentUrlError, "Host is blocked: #{host}"
+        end
+
+        # Check allowed hosts (if configured)
+        if config.client_metadata_document_allowed_hosts.present?
+          unless config.client_metadata_document_allowed_hosts.any? { |pattern| host_matches?(host, pattern) }
+            raise InvalidClientMetadataDocumentUrlError, "Host is not in allowed list: #{host}"
+          end
+        end
+
+        true
+      end
+
+      def host_matches?(host, pattern)
+        if pattern.start_with?("*.")
+          # Wildcard pattern: *.example.com matches foo.example.com
+          suffix = pattern[1..]
+          host.end_with?(suffix) || host == pattern[2..]
+        else
+          host == pattern
+        end
+      end
+
+      def fetch_from_uri(uri)
+        parsed_uri = URI.parse(uri)
+        config = TokenAuthority.config
+
+        # Resolve DNS and validate IP before connecting (SSRF protection)
+        resolved_ip = resolve_and_validate_ip(parsed_uri.host)
+
+        http = Net::HTTP.new(parsed_uri.host, parsed_uri.port)
+        http.use_ssl = true
+        http.open_timeout = config.client_metadata_document_connect_timeout
+        http.read_timeout = config.client_metadata_document_read_timeout
+        http.ipaddr = resolved_ip # Use resolved IP to prevent DNS rebinding
+
+        request = Net::HTTP::Get.new(parsed_uri.request_uri)
+        request["Accept"] = "application/json"
+
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise ClientMetadataDocumentFetchError, "HTTP #{response.code}: #{response.message}"
+        end
+
+        # Check response size
+        max_size = config.client_metadata_document_max_response_size
+        if response.body.bytesize > max_size
+          raise ClientMetadataDocumentFetchError, "Response exceeds maximum size of #{max_size} bytes"
+        end
+
+        JSON.parse(response.body)
+      rescue URI::InvalidURIError => e
+        raise ClientMetadataDocumentFetchError, "Invalid URI: #{e.message}"
+      rescue JSON::ParserError => e
+        raise ClientMetadataDocumentFetchError, "Invalid JSON: #{e.message}"
+      rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT, Errno::ENETUNREACH,
+        Net::OpenTimeout, Net::ReadTimeout, SocketError => e
+        raise ClientMetadataDocumentFetchError, "Connection error: #{e.message}"
+      rescue OpenSSL::SSL::SSLError => e
+        raise ClientMetadataDocumentFetchError, "SSL error: #{e.message}"
+      end
+
+      def resolve_and_validate_ip(host)
+        addresses = Resolv.getaddresses(host)
+
+        if addresses.empty?
+          raise ClientMetadataDocumentFetchError, "Could not resolve host: #{host}"
+        end
+
+        # Validate all resolved IPs are not private
+        addresses.each do |addr|
+          ip = IPAddr.new(addr)
+          if private_ip?(ip)
+            raise ClientMetadataDocumentFetchError, "Host resolves to private IP address"
+          end
+        end
+
+        # Prefer IPv4 addresses over IPv6 for better compatibility
+        ipv4_addresses = addresses.select { |addr| IPAddr.new(addr).ipv4? }
+        ipv4_addresses.first || addresses.first
+      rescue IPAddr::InvalidAddressError => e
+        raise ClientMetadataDocumentFetchError, "Invalid IP address: #{e.message}"
+      rescue Resolv::ResolvError => e
+        raise ClientMetadataDocumentFetchError, "DNS resolution failed: #{e.message}"
+      end
+
+      def private_ip?(ip)
+        PRIVATE_IP_RANGES.any? { |range| range.include?(ip) }
+      end
+
+      def validate_metadata!(uri, metadata)
+        # client_id in metadata must match the URL
+        if metadata["client_id"] != uri
+          raise InvalidClientMetadataDocumentError,
+            "client_id in metadata (#{metadata["client_id"]}) does not match URL (#{uri})"
+        end
+
+        # Must not contain client_secret (public clients only)
+        if metadata["client_secret"].present?
+          raise InvalidClientMetadataDocumentError, "Client metadata document must not contain client_secret"
+        end
+
+        # Must have at least one redirect_uri
+        redirect_uris = metadata["redirect_uris"]
+        if redirect_uris.blank? || !redirect_uris.is_a?(Array) || redirect_uris.empty?
+          raise InvalidClientMetadataDocumentError, "Client metadata document must have redirect_uris"
+        end
+
+        # Validate redirect_uris are valid URLs
+        redirect_uris.each do |redirect_uri|
+          parsed = URI.parse(redirect_uri)
+          unless parsed.is_a?(URI::HTTP) || parsed.is_a?(URI::HTTPS)
+            raise InvalidClientMetadataDocumentError,
+              "Invalid redirect_uri scheme: #{redirect_uri}"
+          end
+        rescue URI::InvalidURIError
+          raise InvalidClientMetadataDocumentError, "Invalid redirect_uri: #{redirect_uri}"
+        end
+
+        true
+      end
+
+      def store_in_cache(uri, metadata)
+        ttl = TokenAuthority.config.client_metadata_document_cache_ttl
+        uri_hash = ClientMetadataDocumentCache.hash_uri(uri)
+
+        ClientMetadataDocumentCache.find_or_initialize_by(uri_hash: uri_hash).tap do |cache|
+          cache.uri = uri
+          cache.metadata = metadata
+          cache.expires_at = Time.current + ttl
+          cache.save!
+        end
+      end
+
+      def debug_event(event_name, **payload)
+        return unless event_logging_enabled?
+        return unless debug_events_enabled?
+        return unless rails_event_available?
+
+        full_payload = {timestamp: Time.current.iso8601(6)}.merge(payload)
+        Rails.event.debug("token_authority.#{event_name}", **full_payload)
+      end
+
+      def event_logging_enabled?
+        TokenAuthority.config.respond_to?(:event_logging_enabled) &&
+          TokenAuthority.config.event_logging_enabled
+      end
+
+      def debug_events_enabled?
+        TokenAuthority.config.respond_to?(:event_logging_debug_events) &&
+          TokenAuthority.config.event_logging_debug_events
+      end
+
+      def rails_event_available?
+        Rails.respond_to?(:event) && Rails.event.present?
+      end
+    end
+  end
+end

data/app/models/token_authority/client_registration_request.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  ##
+  # Service object for validating and processing dynamic client registration requests (RFC 7591)
+  class ClientRegistrationRequest
+    include ActiveModel::Model
+    include ActiveModel::Validations
+
+    VALID_AUTH_METHODS = TokenAuthority::Client::SUPPORTED_AUTH_METHODS
+
+    attr_accessor :redirect_uris,
+      :token_endpoint_auth_method,
+      :grant_types,
+      :response_types,
+      :client_name,
+      :client_uri,
+      :logo_uri,
+      :tos_uri,
+      :policy_uri,
+      :contacts,
+      :scope,
+      :jwks_uri,
+      :jwks,
+      :software_id,
+      :software_version,
+      :software_statement
+
+    validates :redirect_uris, presence: true
+    validate :redirect_uris_are_valid
+    validate :token_endpoint_auth_method_is_allowed
+    validate :grant_types_are_allowed
+    validate :response_types_are_consistent
+    validate :scopes_are_allowed
+    validate :contacts_are_valid_emails
+    validate :jwks_and_jwks_uri_mutually_exclusive
+    validate :jwks_required_for_private_key_jwt
+    validate :software_statement_is_valid
+
+    def initialize(attributes = {})
+      super
+      @token_endpoint_auth_method ||= "client_secret_basic"
+      @grant_types ||= ["authorization_code"]
+      @response_types ||= ["code"]
+    end
+
+    def create_client!
+      raise TokenAuthority::InvalidClientMetadataError, errors.full_messages.join(", ") unless valid?
+
+      merged_attrs = merge_software_statement_claims
+      build_client(merged_attrs).tap(&:save!)
+    end
+
+    private
+
+    def redirect_uris_are_valid
+      return if redirect_uris.blank?
+      return unless redirect_uris.is_a?(Array)
+
+      redirect_uris.each do |uri|
+        parsed = URI.parse(uri)
+        unless parsed.is_a?(URI::HTTP) || parsed.is_a?(URI::HTTPS)
+          errors.add(:redirect_uris, "contains invalid URI scheme: #{uri}")
+          break
+        end
+      rescue URI::InvalidURIError
+        errors.add(:redirect_uris, "contains invalid URI: #{uri}")
+        break
+      end
+    end
+
+    def token_endpoint_auth_method_is_allowed
+      return if token_endpoint_auth_method.blank?
+
+      allowed = TokenAuthority.config.rfc_7591_allowed_token_endpoint_auth_methods
+      unless allowed.include?(token_endpoint_auth_method)
+        errors.add(:token_endpoint_auth_method, "is not allowed: #{token_endpoint_auth_method}")
+      end
+    end
+
+    def grant_types_are_allowed
+      return if grant_types.blank?
+      return unless grant_types.is_a?(Array)
+
+      allowed = TokenAuthority.config.rfc_7591_allowed_grant_types
+      disallowed = grant_types - allowed
+      errors.add(:grant_types, "contains disallowed types: #{disallowed.join(", ")}") if disallowed.any?
+    end
+
+    def response_types_are_consistent
+      return if response_types.blank? || grant_types.blank?
+
+      if grant_types.include?("authorization_code") && !response_types.include?("code")
+        errors.add(:response_types, "must include 'code' when grant_types includes 'authorization_code'")
+      end
+    end
+
+    def scopes_are_allowed
+      return if scope.blank?
+
+      allowed = TokenAuthority.config.rfc_7591_allowed_scopes
+      return if allowed.blank? # If no restrictions configured, allow all
+
+      requested_scopes = scope.to_s.split(/\s+/).reject(&:blank?)
+      disallowed = requested_scopes - allowed
+      errors.add(:scope, "contains disallowed scopes: #{disallowed.join(", ")}") if disallowed.any?
+    end
+
+    def contacts_are_valid_emails
+      return if contacts.blank?
+      return unless contacts.is_a?(Array)
+
+      email_regex = /\A[\w+\-.]+@[a-z\d-]+(\.[a-z\d-]+)*\.[a-z]+\z/i
+      contacts.each do |email|
+        unless email.match?(email_regex)
+          errors.add(:contacts, "contains invalid email: #{email}")
+          break
+        end
+      end
+    end
+
+    def jwks_and_jwks_uri_mutually_exclusive
+      if jwks.present? && jwks_uri.present?
+        errors.add(:base, "jwks and jwks_uri are mutually exclusive")
+      end
+    end
+
+    def jwks_required_for_private_key_jwt
+      return unless token_endpoint_auth_method == "private_key_jwt"
+
+      if jwks.blank? && jwks_uri.blank?
+        errors.add(:base, "jwks or jwks_uri is required when token_endpoint_auth_method is private_key_jwt")
+      end
+    end
+
+    def software_statement_is_valid
+      return if software_statement.blank?
+
+      begin
+        @parsed_software_statement = parse_software_statement
+      rescue TokenAuthority::InvalidSoftwareStatementError => e
+        errors.add(:software_statement, e.message)
+      rescue TokenAuthority::UnapprovedSoftwareStatementError => e
+        errors.add(:software_statement, e.message)
+      end
+    end
+
+    def parse_software_statement
+      jwks = TokenAuthority.config.rfc_7591_software_statement_jwks
+      if jwks.present?
+        SoftwareStatement.decode_and_verify(software_statement, jwks: jwks)
+      elsif TokenAuthority.config.rfc_7591_software_statement_required
+        raise TokenAuthority::UnapprovedSoftwareStatementError
+      else
+        SoftwareStatement.decode(software_statement)
+      end
+    end
+
+    def merge_software_statement_claims
+      base_attrs = registration_attributes
+      return base_attrs unless @parsed_software_statement
+
+      # Software statement claims take precedence per RFC 7591
+      @parsed_software_statement.claims.compact.merge(base_attrs.compact) do |_key, ss_val, req_val|
+        ss_val.present? ? ss_val : req_val
+      end
+    end
+
+    def registration_attributes
+      {
+        redirect_uris: redirect_uris,
+        token_endpoint_auth_method: token_endpoint_auth_method,
+        grant_types: grant_types,
+        response_types: response_types,
+        client_name: client_name,
+        client_uri: client_uri,
+        logo_uri: logo_uri,
+        tos_uri: tos_uri,
+        policy_uri: policy_uri,
+        contacts: contacts,
+        scope: scope,
+        jwks_uri: jwks_uri,
+        jwks: jwks,
+        software_id: software_id,
+        software_version: software_version
+      }
+    end
+
+    def build_client(attrs)
+      client_type = (attrs[:token_endpoint_auth_method] == "none") ? "public" : "confidential"
+
+      TokenAuthority::Client.new(
+        name: attrs[:client_name] || "Dynamic Client",
+        redirect_uris: attrs[:redirect_uris],
+        client_type: client_type,
+        token_endpoint_auth_method: attrs[:token_endpoint_auth_method] || "client_secret_basic",
+        grant_types: attrs[:grant_types],
+        response_types: attrs[:response_types],
+        scope: attrs[:scope],
+        client_uri: attrs[:client_uri],
+        logo_uri: attrs[:logo_uri],
+        tos_uri: attrs[:tos_uri],
+        policy_uri: attrs[:policy_uri],
+        contacts: attrs[:contacts],
+        jwks_uri: attrs[:jwks_uri],
+        jwks: attrs[:jwks],
+        software_id: attrs[:software_id],
+        software_version: attrs[:software_version],
+        software_statement: software_statement,
+        dynamically_registered: true
+      )
+    end
+  end
+end

data/app/models/token_authority/client_registration_response.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  ##
+  # Value object for building RFC 7591-compliant client registration response
+  class ClientRegistrationResponse
+    attr_reader :client
+
+    def initialize(client:)
+      @client = client
+    end
+
+    def to_h
+      response = {
+        client_id: client.public_id,
+        client_id_issued_at: client.client_id_issued_at.to_i
+      }
+
+      # Only include client_secret for confidential clients
+      if client.confidential_client_type?
+        response[:client_secret] = client.client_secret
+        response[:client_secret_expires_at] = client.client_secret_expires_at&.to_i || 0
+      end
+
+      # Echo back all registered metadata
+      response.merge!(metadata)
+
+      response.compact
+    end
+
+    def to_json(*)
+      to_h.to_json
+    end
+
+    private
+
+    def metadata
+      {
+        redirect_uris: client.redirect_uris,
+        token_endpoint_auth_method: client.token_endpoint_auth_method,
+        grant_types: client.grant_types,
+        response_types: client.response_types,
+        client_name: client.name,
+        client_uri: client.client_uri,
+        logo_uri: client.logo_uri,
+        tos_uri: client.tos_uri,
+        policy_uri: client.policy_uri,
+        contacts: client.contacts,
+        scope: client.scope,
+        jwks_uri: client.jwks_uri,
+        jwks: client.jwks,
+        software_id: client.software_id,
+        software_version: client.software_version
+        # Note: software_statement is intentionally NOT echoed per RFC 7591
+      }
+    end
+  end
+end

data/app/models/token_authority/jwks_cache.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  ##
+  # Stores cached JWKS fetched from remote URIs
+  class JwksCache < ApplicationRecord
+    validates :uri_hash, presence: true, uniqueness: true
+    validates :uri, presence: true
+    validates :jwks, 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
+
+    def to_jwk_set
+      JWT::JWK::Set.new(jwks)
+    end
+  end
+end

data/app/models/token_authority/jwks_fetcher.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module TokenAuthority
+  ##
+  # Service for fetching and caching JWKS from a remote URI using database storage
+  class JwksFetcher
+    extend TokenAuthority::Instrumentation
+
+    class FetchError < StandardError; end
+
+    class << self
+      def fetch(uri)
+        instrument("jwks.fetch", uri: uri) do |payload|
+          cached = JwksCache.find_by_uri(uri)
+
+          if cached && !cached.expired?
+            payload[:cache_hit] = true
+            return cached.to_jwk_set
+          end
+
+          payload[:cache_hit] = false
+
+          # Fetch fresh data and update/create cache entry
+          jwks_data = fetch_from_uri(uri)
+          store_in_cache(uri, jwks_data)
+
+          JWT::JWK::Set.new(jwks_data)
+        end
+      end
+
+      def clear_cache(uri)
+        JwksCache.find_by_uri(uri)&.destroy
+      end
+
+      def cleanup_expired!
+        JwksCache.cleanup_expired!
+      end
+
+      private
+
+      def fetch_from_uri(uri)
+        parsed_uri = URI.parse(uri)
+        raise FetchError, "Invalid URI scheme: #{uri}" unless parsed_uri.is_a?(URI::HTTPS)
+
+        response = Net::HTTP.get_response(parsed_uri)
+        raise FetchError, "HTTP #{response.code}: #{response.message}" unless response.is_a?(Net::HTTPSuccess)
+
+        JSON.parse(response.body)
+      rescue URI::InvalidURIError => e
+        raise FetchError, "Invalid JWKS URI: #{e.message}"
+      rescue JSON::ParserError => e
+        raise FetchError, "Invalid JWKS JSON: #{e.message}"
+      rescue => e
+        raise FetchError, "Failed to fetch JWKS: #{e.message}"
+      end
+
+      def store_in_cache(uri, jwks_data)
+        ttl = TokenAuthority.config.rfc_7591_jwks_cache_ttl
+        uri_hash = JwksCache.hash_uri(uri)
+
+        JwksCache.find_or_initialize_by(uri_hash: uri_hash).tap do |cache|
+          cache.uri = uri
+          cache.jwks = jwks_data
+          cache.expires_at = Time.current + ttl
+          cache.save!
+        end
+      end
+    end
+  end
+end