omniauth_openid_federation 1.0.0

data/lib/omniauth_openid_federation/federation/entity_statement.rb

@@ -0,0 +1,331 @@
+require "net/http"
+require "digest"
+require "jwt"
+require "base64"
+require "openssl"
+require "timeout"
+require_relative "../key_extractor"
+require_relative "../logger"
+require_relative "../errors"
+require_relative "../configuration"
+require_relative "../http_client"
+require_relative "../utils"
+require_relative "entity_statement_parser"
+
+# Entity Statement implementation for OpenID Federation 1.0
+# @see https://openid.net/specs/openid-federation-1_0.html OpenID Federation 1.0 Specification
+# @see https://openid.github.io/federation/main.html OpenID Federation Documentation
+#
+# Entity Statements are self-signed JWTs that contain provider metadata and JWKS.
+# This implementation supports:
+# - Fetching entity statements from /.well-known/openid-federation endpoint (Section 9)
+# - Fingerprint validation (SHA-256 hash) for integrity verification
+# - Previous statement validation for update verification
+# - Metadata extraction for OpenID Provider configuration
+#
+# Note: This implementation handles self-signed entity statements directly.
+# Full trust chain resolution (Section 10) is not implemented as it's not required
+# for direct entity statement validation use cases.
+module OmniauthOpenidFederation
+  module Federation
+    # Entity Statement implementation for OpenID Federation 1.0
+    #
+    # @example Fetch and validate an entity statement from full URL
+    #   statement = EntityStatement.fetch!(
+    #     "https://provider.example.com/.well-known/openid-federation",
+    #     fingerprint: "expected-fingerprint-hash"
+    #   )
+    #   metadata = statement.parse
+    #
+    # @example Fetch and validate an entity statement from issuer and endpoint
+    #   statement = EntityStatement.fetch_from_issuer!(
+    #     "https://provider.example.com",
+    #     entity_statement_endpoint: "/.well-known/openid-federation",
+    #     fingerprint: "expected-fingerprint-hash"
+    #   )
+    #   metadata = statement.parse
+    class EntityStatement
+      # Compatibility aliases for backward compatibility
+      FetchError = OmniauthOpenidFederation::FetchError
+      ValidationError = OmniauthOpenidFederation::ValidationError
+      attr_reader :entity_statement, :fingerprint, :metadata
+
+      # Fetch entity statement from URL
+      #
+      # @param url [String] The URL to fetch the entity statement from
+      # @param fingerprint [String, nil] Expected SHA-256 fingerprint for validation
+      # @param previous_statement [String, EntityStatement, Hash, nil] Previous statement for validation
+      # @param timeout [Integer] HTTP request timeout in seconds (default: 10)
+      # @return [EntityStatement] The fetched and validated entity statement
+      # @raise [FetchError] If fetching fails
+      # @raise [ValidationError] If validation fails
+
+      def initialize(entity_statement_content, fingerprint: nil)
+        @entity_statement = entity_statement_content
+        @fingerprint = fingerprint || calculate_fingerprint
+        @metadata = nil
+      end
+
+      # Fetch entity statement from issuer and endpoint path
+      #
+      # @param issuer_uri [String, URI] Issuer URI (e.g., "https://provider.example.com")
+      # @param entity_statement_endpoint [String, nil] Entity statement endpoint path (defaults to "/.well-known/openid-federation")
+      # @param fingerprint [String, nil] Expected SHA-256 fingerprint for validation
+      # @param previous_statement [String, EntityStatement, Hash, nil] Previous statement for validation
+      # @param timeout [Integer] HTTP request timeout in seconds (default: 10)
+      # @return [EntityStatement] The fetched and validated entity statement
+      # @raise [FetchError] If fetching fails
+      # @raise [ValidationError] If validation fails
+      def self.fetch_from_issuer!(issuer_uri, entity_statement_endpoint: nil, fingerprint: nil, previous_statement: nil, timeout: 10)
+        url = OmniauthOpenidFederation::Utils.build_entity_statement_url(
+          issuer_uri,
+          entity_statement_endpoint: entity_statement_endpoint
+        )
+        fetch!(url, fingerprint: fingerprint, previous_statement: previous_statement, timeout: timeout)
+      end
+
+      # Fetch entity statement from URL
+      #
+      # @param url [String] The URL to fetch the entity statement from
+      # @param fingerprint [String, nil] Expected SHA-256 fingerprint for validation
+      # @param previous_statement [String, EntityStatement, Hash, nil] Previous statement for validation
+      # @param timeout [Integer] HTTP request timeout in seconds (default: 10)
+      # @return [EntityStatement] The fetched and validated entity statement
+      # @raise [FetchError] If fetching fails
+      # @raise [ValidationError] If validation fails
+      def self.fetch!(url, fingerprint: nil, previous_statement: nil, timeout: 10)
+        # Use HttpClient for retry logic and configurable SSL verification
+        # Note: HttpClient uses HTTP gem, but entity statements might need Net::HTTP
+        # For now, we'll use a simple HTTP.get approach with HttpClient's retry logic
+        begin
+          # Convert URL to URI for HttpClient
+          response = HttpClient.get(url, timeout: timeout)
+        rescue OmniauthOpenidFederation::NetworkError => e
+          OmniauthOpenidFederation::Logger.error("[EntityStatement] Failed to fetch entity statement: #{e.message}")
+          raise FetchError, "Failed to fetch entity statement from #{url}: #{e.message}", e.backtrace
+        end
+
+        unless response.status.success?
+          error_msg = "Failed to fetch entity statement from #{url}: HTTP #{response.status}"
+          OmniauthOpenidFederation::Logger.error("[EntityStatement] #{error_msg}")
+          raise FetchError, error_msg
+        end
+
+        # HTTP gem returns body as StringIO or similar, convert to string
+        entity_statement = response.body.to_s
+
+        instance = new(entity_statement, fingerprint: nil) # Don't set fingerprint in constructor
+
+        # Validate using full OpenID Federation validation (includes signature validation)
+        # This is required for OpenID Federation compliance
+        begin
+          EntityStatementParser.parse(entity_statement, validate_signature: true, validate_full: true)
+          OmniauthOpenidFederation::Logger.debug("[EntityStatement] Full validation successful")
+        rescue SignatureError, ValidationError => e
+          error_msg = "Entity statement validation failed: #{e.message}"
+          OmniauthOpenidFederation::Logger.error("[EntityStatement] #{error_msg}")
+          # Instrument entity statement validation failure
+          OmniauthOpenidFederation::Instrumentation.notify_entity_statement_validation_failed(
+            entity_statement_url: url,
+            validation_step: "full_validation",
+            error_message: e.message,
+            error_class: e.class.name
+          )
+          raise ValidationError, error_msg, e.backtrace
+        end
+
+        # Validate if fingerprint provided
+        if fingerprint
+          calculated_fingerprint = instance.calculate_fingerprint
+          unless instance.validate_fingerprint(fingerprint)
+            error_msg = "Entity statement fingerprint mismatch. Expected: #{fingerprint}, Got: #{calculated_fingerprint}"
+            OmniauthOpenidFederation::Logger.error("[EntityStatement] #{error_msg}")
+            # Instrument fingerprint mismatch
+            OmniauthOpenidFederation::Instrumentation.notify_fingerprint_mismatch(
+              entity_statement_url: url,
+              expected_fingerprint: fingerprint,
+              calculated_fingerprint: calculated_fingerprint
+            )
+            raise ValidationError, error_msg
+          end
+          OmniauthOpenidFederation::Logger.debug("[EntityStatement] Fingerprint validation successful: #{fingerprint}")
+        end
+
+        # Validate against previous statement if provided
+        if previous_statement
+          unless instance.validate_against_previous(previous_statement)
+            error_msg = "Entity statement validation against previous statement failed"
+            OmniauthOpenidFederation::Logger.error("[EntityStatement] #{error_msg}")
+            raise ValidationError, error_msg
+          end
+          OmniauthOpenidFederation::Logger.debug("[EntityStatement] Previous statement validation successful")
+        end
+
+        instance
+      end
+
+      # Calculate SHA-256 fingerprint of the entity statement
+      #
+      # @return [String] The lowercase hexadecimal fingerprint
+      def calculate_fingerprint
+        Digest::SHA256.hexdigest(entity_statement).downcase
+      end
+
+      # Validate fingerprint against expected value
+      #
+      # @param expected_fingerprint [String] The expected fingerprint
+      # @return [Boolean] true if fingerprints match
+      def validate_fingerprint(expected_fingerprint)
+        calculated = fingerprint.downcase
+        expected = expected_fingerprint.to_s.downcase
+        calculated == expected
+      end
+
+      # Validate against a previous entity statement
+      #
+      # @param previous_statement [String, EntityStatement, Hash] The previous statement to validate against
+      # @return [Boolean] true if validation passes
+      def validate_against_previous(previous_statement)
+        # Decode current statement
+        current_payload = decode_payload
+
+        # Handle different input types
+        previous_payload = if previous_statement.is_a?(String)
+          decode_jwt_payload(previous_statement)
+        elsif previous_statement.instance_of?(::OmniauthOpenidFederation::Federation::EntityStatement)
+          # If it's an EntityStatement instance, decode its payload
+          previous_statement.decode_payload
+        else
+          previous_statement
+        end
+
+        # Check if issuer matches
+        return false unless current_payload["iss"] == previous_payload["iss"]
+
+        # Check if this is a valid update (e.g., exp time is later)
+        current_exp = current_payload["exp"]
+        previous_exp = previous_payload["exp"]
+
+        return false if current_exp && previous_exp && current_exp < previous_exp
+
+        # Additional validation can be added here (e.g., check authority_hints)
+        true
+      end
+
+      # Parse entity statement and extract metadata
+      #
+      # @return [Hash] Hash containing issuer, subject, expiration, JWKS, and provider metadata
+      def parse
+        return @metadata if @metadata
+
+        payload = decode_payload
+
+        # Extract provider metadata
+        metadata_section = payload.fetch("metadata", {})
+        metadata_section.fetch("openid_provider", {})
+
+        # Extract entity JWKS - ensure it's a hash with keys array
+        entity_jwks = payload.fetch("jwks", {})
+        # Normalize to ensure it has :keys or "keys" key
+        if entity_jwks.nil? || !entity_jwks.is_a?(Hash)
+          entity_jwks = {keys: []}
+        elsif !entity_jwks.key?(:keys) && !entity_jwks.key?("keys")
+          entity_jwks = {keys: []}
+        end
+
+        # Extract all entity types from metadata
+        metadata_section = payload.fetch("metadata", {})
+        provider_metadata = metadata_section.fetch("openid_provider", {})
+        rp_metadata = metadata_section.fetch("openid_relying_party", {})
+
+        @metadata = {
+          issuer: payload["iss"],
+          sub: payload["sub"],
+          exp: payload["exp"],
+          iat: payload["iat"],
+          jwks: entity_jwks,
+          metadata: {},
+          # Advanced claims (Entity Configuration specific)
+          authority_hints: payload["authority_hints"] || payload[:authority_hints],
+          trust_marks: payload["trust_marks"] || payload[:trust_marks],
+          trust_mark_issuers: payload["trust_mark_issuers"] || payload[:trust_mark_issuers],
+          trust_mark_owners: payload["trust_mark_owners"] || payload[:trust_mark_owners],
+          # Advanced claims (Subordinate Statement specific)
+          metadata_policy: payload["metadata_policy"] || payload[:metadata_policy],
+          metadata_policy_crit: payload["metadata_policy_crit"] || payload[:metadata_policy_crit],
+          constraints: payload["constraints"] || payload[:constraints],
+          source_endpoint: payload["source_endpoint"] || payload[:source_endpoint],
+          # Other claims
+          crit: payload["crit"] || payload[:crit],
+          # Determine statement type
+          is_entity_configuration: (payload["iss"] == payload["sub"]),
+          is_subordinate_statement: (payload["iss"] != payload["sub"])
+        }
+
+        # Extract OpenID Provider metadata if present
+        if provider_metadata.any?
+          @metadata[:metadata][:openid_provider] = {
+            issuer: provider_metadata["issuer"],
+            authorization_endpoint: provider_metadata["authorization_endpoint"],
+            token_endpoint: provider_metadata["token_endpoint"],
+            userinfo_endpoint: provider_metadata["userinfo_endpoint"],
+            jwks_uri: provider_metadata["jwks_uri"],
+            signed_jwks_uri: provider_metadata["signed_jwks_uri"],
+            end_session_endpoint: provider_metadata["end_session_endpoint"],
+            client_registration_types_supported: provider_metadata["client_registration_types_supported"],
+            federation_registration_endpoint: provider_metadata["federation_registration_endpoint"]
+          }
+        end
+
+        # Extract OpenID Relying Party metadata if present
+        if rp_metadata.any?
+          @metadata[:metadata][:openid_relying_party] = {
+            application_type: rp_metadata["application_type"],
+            redirect_uris: rp_metadata["redirect_uris"],
+            client_registration_types: rp_metadata["client_registration_types"],
+            signed_jwks_uri: rp_metadata["signed_jwks_uri"],
+            jwks_uri: rp_metadata["jwks_uri"],
+            organization_name: rp_metadata["organization_name"],
+            logo_uri: rp_metadata["logo_uri"],
+            grant_types: rp_metadata["grant_types"],
+            response_types: rp_metadata["response_types"],
+            scope: rp_metadata["scope"]
+          }
+        end
+
+        @metadata
+      end
+
+      # Save entity statement to file
+      #
+      # @param file_path [String] Path to save the entity statement
+      def save_to_file(file_path)
+        File.write(file_path, entity_statement)
+      end
+
+      # Decode and return the JWT payload
+      #
+      # @return [Hash] The decoded JWT payload
+      def decode_payload
+        decode_jwt_payload(entity_statement)
+      end
+
+      private
+
+      # Standard JWT has 3 parts: header.payload.signature
+      JWT_PARTS_COUNT = 3
+
+      def decode_jwt_payload(jwt_string)
+        jwt_parts = jwt_string.split(".")
+        raise ValidationError, "Invalid JWT format" if jwt_parts.length != JWT_PARTS_COUNT
+
+        # Decode payload (second part)
+        JSON.parse(Base64.urlsafe_decode64(jwt_parts[1]))
+      rescue JSON::ParserError => e
+        raise ValidationError, "Failed to parse entity statement payload: #{e.message}"
+      rescue ArgumentError => e
+        raise ValidationError, "Failed to decode entity statement: #{e.message}"
+      end
+    end
+  end
+end

data/lib/omniauth_openid_federation/federation/entity_statement_builder.rb

@@ -0,0 +1,188 @@
+require "jwt"
+require "base64"
+require "openssl"
+require "time"
+require_relative "../logger"
+require_relative "../errors"
+
+# Entity Statement Builder for OpenID Federation 1.0
+# @see https://openid.net/specs/openid-federation-1_0.html OpenID Federation 1.0 Specification
+#
+# Builds self-signed entity statement JWTs that contain provider metadata and JWKS.
+# Entity statements are used to publish provider configuration and enable signed JWKS support.
+#
+# @example Generate an entity statement
+#   builder = EntityStatementBuilder.new(
+#     issuer: "https://provider.example.com",
+#     subject: "https://provider.example.com",
+#     private_key: private_key,
+#     jwks: jwks_hash,
+#     metadata: {
+#       openid_provider: {
+#         issuer: "https://provider.example.com",
+#         authorization_endpoint: "https://provider.example.com/oauth2/authorize",
+#         token_endpoint: "https://provider.example.com/oauth2/token",
+#         userinfo_endpoint: "https://provider.example.com/oauth2/userinfo",
+#         jwks_uri: "https://provider.example.com/.well-known/jwks.json",
+#         signed_jwks_uri: "https://provider.example.com/.well-known/signed-jwks.json"
+#       }
+#     }
+#   )
+#   entity_statement_jwt = builder.build
+module OmniauthOpenidFederation
+  module Federation
+    # Entity Statement Builder for OpenID Federation 1.0
+    #
+    # Builds self-signed entity statement JWTs for publishing provider configuration.
+    class EntityStatementBuilder
+      # @param issuer [String] Entity issuer (typically the provider URL)
+      # @param subject [String] Entity subject (typically same as issuer for self-issued statements)
+      # @param private_key [OpenSSL::PKey::RSA] Private key for signing the entity statement
+      # @param jwks [Hash] JWKS hash with "keys" array containing public keys
+      # @param metadata [Hash] Provider metadata hash with openid_provider section
+      # @param expiration_seconds [Integer] Expiration time in seconds from now (default: 86400 = 24 hours)
+      # @param kid [String, nil] Key ID to use for signing (defaults to first key's kid in JWKS)
+      # @param authority_hints [Array<String>, nil] Optional: Array of Entity Identifiers for Immediate Superiors (Entity Configuration only)
+      # @param trust_marks [Array<Hash>, nil] Optional: Array of Trust Mark objects (Entity Configuration only)
+      # @param trust_mark_issuers [Hash, nil] Optional: Trust Mark issuers configuration (Trust Anchor only)
+      # @param trust_mark_owners [Hash, nil] Optional: Trust Mark owners configuration (Trust Anchor only)
+      # @param metadata_policy [Hash, nil] Optional: Metadata policy (Subordinate Statement only)
+      # @param metadata_policy_crit [Array<String>, nil] Optional: Critical metadata policy operators (Subordinate Statement only)
+      # @param constraints [Hash, nil] Optional: Trust Chain constraints (Subordinate Statement only)
+      # @param source_endpoint [String, nil] Optional: Fetch endpoint URL (Subordinate Statement only)
+      # @param crit [Array<String>, nil] Optional: Critical claims that must be understood
+      def initialize(issuer:, subject:, private_key:, jwks:, metadata:, expiration_seconds: 86400, kid: nil,
+        authority_hints: nil, trust_marks: nil, trust_mark_issuers: nil, trust_mark_owners: nil,
+        metadata_policy: nil, metadata_policy_crit: nil, constraints: nil, source_endpoint: nil, crit: nil)
+        @issuer = issuer
+        @subject = subject
+        @private_key = private_key
+        @jwks = normalize_jwks(jwks)
+        @metadata = metadata
+        @expiration_seconds = expiration_seconds
+        @kid = kid || extract_kid_from_jwks(@jwks)
+        @authority_hints = authority_hints
+        @trust_marks = trust_marks
+        @trust_mark_issuers = trust_mark_issuers
+        @trust_mark_owners = trust_mark_owners
+        @metadata_policy = metadata_policy
+        @metadata_policy_crit = metadata_policy_crit
+        @constraints = constraints
+        @source_endpoint = source_endpoint
+        @crit = crit
+      end
+
+      # Build and sign the entity statement JWT
+      #
+      # @return [String] The signed entity statement JWT string
+      # @raise [ConfigurationError] If required parameters are missing
+      # @raise [SignatureError] If signing fails
+      def build
+        validate_parameters
+
+        payload = build_payload
+
+        # Build JWT header
+        # Per OpenID Federation 1.0 Section 3.1: typ MUST be "entity-statement+jwt"
+        header = {
+          alg: "RS256",
+          typ: "entity-statement+jwt",
+          kid: @kid
+        }
+
+        begin
+          JWT.encode(payload, @private_key, "RS256", header)
+        rescue => e
+          error_msg = "Failed to sign entity statement: #{e.class} - #{e.message}"
+          OmniauthOpenidFederation::Logger.error("[EntityStatementBuilder] #{error_msg}")
+          raise SignatureError, error_msg, e.backtrace
+        end
+      end
+
+      private
+
+      def validate_parameters
+        raise ConfigurationError, "Issuer is required" if @issuer.nil? || @issuer.empty?
+        raise ConfigurationError, "Subject is required" if @subject.nil? || @subject.empty?
+        raise ConfigurationError, "Private key is required" if @private_key.nil?
+        raise ConfigurationError, "JWKS is required" if @jwks.nil? || @jwks.empty?
+        raise ConfigurationError, "Metadata is required" if @metadata.nil? || @metadata.empty?
+        raise ConfigurationError, "JWKS must contain at least one key" if @jwks["keys"].nil? || @jwks["keys"].empty?
+        raise ConfigurationError, "Key ID (kid) is required" if @kid.nil? || @kid.empty?
+      end
+
+      def build_payload
+        now = Time.now.to_i
+        is_entity_configuration = (@issuer == @subject)
+        is_subordinate_statement = !is_entity_configuration
+
+        payload = {
+          iss: @issuer,
+          sub: @subject,
+          iat: now,
+          exp: now + @expiration_seconds,
+          jwks: @jwks,
+          metadata: @metadata
+        }
+
+        # Entity Configuration specific claims
+        if is_entity_configuration
+          payload[:authority_hints] = @authority_hints if @authority_hints
+          payload[:trust_marks] = @trust_marks if @trust_marks
+          payload[:trust_mark_issuers] = @trust_mark_issuers if @trust_mark_issuers
+          payload[:trust_mark_owners] = @trust_mark_owners if @trust_mark_owners
+        end
+
+        # Subordinate Statement specific claims
+        if is_subordinate_statement
+          payload[:metadata_policy] = @metadata_policy if @metadata_policy
+          payload[:metadata_policy_crit] = @metadata_policy_crit if @metadata_policy_crit
+          payload[:constraints] = @constraints if @constraints
+          payload[:source_endpoint] = @source_endpoint if @source_endpoint
+        end
+
+        # Common optional claims
+        payload[:crit] = @crit if @crit
+
+        payload
+      end
+
+      def normalize_jwks(jwks)
+        # Ensure JWKS is a hash with "keys" array
+        if jwks.is_a?(Hash)
+          # If it has :keys or "keys", use as-is
+          if jwks.key?(:keys) || jwks.key?("keys")
+            keys = jwks[:keys] || jwks["keys"]
+            {"keys" => normalize_keys(keys)}
+          else
+            # If it's just a hash, wrap it
+            {"keys" => [jwks]}
+          end
+        elsif jwks.is_a?(Array)
+          {"keys" => normalize_keys(jwks)}
+        else
+          raise ConfigurationError, "JWKS must be a Hash or Array"
+        end
+      end
+
+      def normalize_keys(keys)
+        keys.map do |key|
+          if key.is_a?(Hash)
+            # Convert symbol keys to string keys
+            key.transform_keys(&:to_s)
+          else
+            key
+          end
+        end
+      end
+
+      def extract_kid_from_jwks(jwks)
+        keys = jwks["keys"] || jwks[:keys] || []
+        return nil if keys.empty?
+
+        first_key = keys.first
+        first_key["kid"] || first_key[:kid]
+      end
+    end
+  end
+end

data/lib/omniauth_openid_federation/federation/entity_statement_fetcher.rb

@@ -0,0 +1,142 @@
+require_relative "entity_statement"
+require_relative "../logger"
+require_relative "../errors"
+require_relative "../http_client"
+require_relative "../utils"
+
+# Entity Statement Fetcher abstraction for OpenID Federation
+# @see https://openid.net/specs/openid-federation-1_0.html OpenID Federation 1.0 Specification
+#
+# Provides a pluggable interface for fetching entity statements from various sources.
+# This abstraction improves testability and allows different fetching strategies.
+module OmniauthOpenidFederation
+  module Federation
+    module EntityStatementFetcher
+      # Base class for entity statement fetchers
+      # Subclasses must implement #fetch_entity_statement
+      class Base
+        # Get the entity statement (cached)
+        #
+        # @return [EntityStatement] The entity statement instance
+        def entity_statement
+          @entity_statement ||= begin
+            content = fetch_entity_statement
+            EntityStatement.new(content)
+          end
+        end
+
+        # Reload the entity statement (clear cache)
+        #
+        # @return [void]
+        def reload!
+          @entity_statement = nil
+        end
+
+        private
+
+        # Fetch the entity statement content
+        # Must be implemented by subclasses
+        #
+        # @return [String] The entity statement JWT string
+        # @raise [NotImplementedError] If not implemented by subclass
+        def fetch_entity_statement
+          raise NotImplementedError, "#{self.class} must implement #fetch_entity_statement"
+        end
+      end
+
+      # Fetches entity statement from a federation URL
+      class UrlFetcher < Base
+        attr_reader :entity_statement_url, :fingerprint, :timeout
+
+        # Initialize URL fetcher
+        #
+        # @param entity_statement_url [String] The URL to fetch from
+        # @param fingerprint [String, nil] Expected SHA-256 fingerprint for verification
+        # @param timeout [Integer] HTTP timeout in seconds (default: 10)
+        def initialize(entity_statement_url, fingerprint: nil, timeout: 10)
+          @entity_statement_url = entity_statement_url
+          @fingerprint = fingerprint
+          @timeout = timeout
+        end
+
+        private
+
+        def fetch_entity_statement
+          OmniauthOpenidFederation::Logger.debug("[EntityStatementFetcher::UrlFetcher] Fetching entity statement from #{Utils.sanitize_uri(@entity_statement_url)}")
+
+          begin
+            response = HttpClient.get(@entity_statement_url, timeout: @timeout)
+          rescue OmniauthOpenidFederation::NetworkError => e
+            sanitized_uri = Utils.sanitize_uri(@entity_statement_url)
+            OmniauthOpenidFederation::Logger.error("[EntityStatementFetcher::UrlFetcher] Failed to fetch entity statement from #{sanitized_uri}: #{e.message}")
+            raise FetchError, "Failed to fetch entity statement from #{sanitized_uri}: #{e.message}", e.backtrace
+          end
+
+          unless response.status.success?
+            sanitized_uri = Utils.sanitize_uri(@entity_statement_url)
+            error_msg = "Failed to fetch entity statement from #{sanitized_uri}: HTTP #{response.status}"
+            OmniauthOpenidFederation::Logger.error("[EntityStatementFetcher::UrlFetcher] #{error_msg}")
+            raise FetchError, error_msg
+          end
+
+          entity_statement_content = response.body.to_s
+
+          # Validate fingerprint if provided
+          if @fingerprint
+            temp_statement = EntityStatement.new(entity_statement_content)
+            calculated_fingerprint = temp_statement.calculate_fingerprint
+            unless calculated_fingerprint == @fingerprint
+              error_msg = "Entity statement fingerprint mismatch. Expected: #{@fingerprint}, Got: #{calculated_fingerprint}"
+              OmniauthOpenidFederation::Logger.error("[EntityStatementFetcher::UrlFetcher] #{error_msg}")
+              # Instrument fingerprint mismatch
+              OmniauthOpenidFederation::Instrumentation.notify_fingerprint_mismatch(
+                entity_statement_url: @entity_statement_url,
+                expected_fingerprint: @fingerprint,
+                calculated_fingerprint: calculated_fingerprint
+              )
+              raise ValidationError, error_msg
+            end
+          end
+
+          entity_statement_content
+        end
+      end
+
+      # Fetches entity statement from a local file
+      class FileFetcher < Base
+        attr_reader :file_path
+
+        # Initialize file fetcher
+        #
+        # @param file_path [String] Path to the entity statement file
+        # @param allowed_dirs [Array<String>, nil] Allowed directories for path validation (default: Rails.root/config if Rails available)
+        def initialize(file_path, allowed_dirs: nil)
+          @file_path = file_path
+          @allowed_dirs = allowed_dirs || ((defined?(Rails) && Rails.root) ? [Rails.root.join("config").to_s] : nil)
+        end
+
+        private
+
+        def fetch_entity_statement
+          # Validate file path to prevent path traversal
+          validated_path = Utils.validate_file_path!(
+            @file_path,
+            allowed_dirs: @allowed_dirs
+          )
+
+          unless File.exist?(validated_path)
+            sanitized_path = Utils.sanitize_path(validated_path)
+            OmniauthOpenidFederation::Logger.warn("[EntityStatementFetcher::FileFetcher] Entity statement file not found: #{sanitized_path}")
+            raise FetchError, "Entity statement file not found: #{sanitized_path}"
+          end
+
+          OmniauthOpenidFederation::Logger.debug("[EntityStatementFetcher::FileFetcher] Loading entity statement from file: #{Utils.sanitize_path(validated_path)}")
+          File.read(validated_path).strip
+        rescue SecurityError => e
+          OmniauthOpenidFederation::Logger.error("[EntityStatementFetcher::FileFetcher] #{e.message}")
+          raise FetchError, e.message, e.backtrace
+        end
+      end
+    end
+  end
+end