omniauth_openid_federation 1.0.0

data/sig/federation.rbs

@@ -0,0 +1,218 @@
+module OmniauthOpenidFederation
+  module Federation
+    class EntityStatement
+      attr_reader entity_statement: String
+      attr_reader fingerprint: String
+      attr_reader metadata: Hash[Symbol, untyped]?
+
+      def initialize: (String entity_statement_content, ?fingerprint: String?) -> void
+
+      def self.fetch_from_issuer!: (
+        String | URI issuer_uri,
+        ?entity_statement_endpoint: String?,
+        ?fingerprint: String?,
+        ?previous_statement: untyped,
+        ?timeout: Integer
+      ) -> EntityStatement
+
+      def self.fetch!: (
+        String url,
+        ?fingerprint: String?,
+        ?previous_statement: untyped,
+        ?timeout: Integer
+      ) -> EntityStatement
+
+      def calculate_fingerprint: () -> String
+      def validate_fingerprint: (String expected_fingerprint) -> bool
+      def validate_against_previous: (untyped previous_statement) -> bool
+      def parse: () -> Hash[Symbol, untyped]
+      def save_to_file: (String file_path) -> void
+      def decode_payload: () -> Hash[String, untyped]
+    end
+
+    module EntityStatementHelper
+      def self.parse_for_signed_jwks: (String entity_statement_path) -> Hash[Symbol, untyped]?
+      def self.parse_for_signed_jwks_from_content: (String entity_statement_content) -> Hash[Symbol, untyped]?
+    end
+
+    class EntityStatementParser
+      def self.parse: (
+        String jwt_string,
+        ?validate_signature: bool,
+        ?validate_full: bool,
+        ?issuer_entity_configuration: untyped
+      ) -> Hash[Symbol, untyped]
+
+      def initialize: (
+        String jwt_string,
+        ?validate_signature: bool,
+        ?validate_full: bool,
+        ?issuer_entity_configuration: untyped
+      ) -> void
+
+      def parse: () -> Hash[Symbol, untyped]
+    end
+
+    class EntityStatementValidator
+      def initialize: (
+        jwt_string: String,
+        ?issuer_entity_configuration: untyped,
+        ?clock_skew_tolerance: Integer?
+      ) -> void
+
+      def validate!: () -> void
+    end
+
+    class EntityStatementBuilder
+      def initialize: (
+        issuer: String,
+        subject: String,
+        private_key: untyped,
+        jwks: Hash[String, untyped],
+        metadata: Hash[String, untyped],
+        ?expiration_seconds: Integer,
+        ?kid: String?,
+        ?authority_hints: Array[String]?,
+        ?trust_marks: Array[Hash[String, untyped]]?,
+        ?trust_mark_issuers: Hash[String, untyped]?,
+        ?trust_mark_owners: Hash[String, untyped]?,
+        ?metadata_policy: Hash[String, untyped]?,
+        ?metadata_policy_crit: Array[String]?,
+        ?constraints: Hash[String, untyped]?,
+        ?source_endpoint: String?,
+        ?crit: Array[String]?
+      ) -> void
+
+      def build: () -> String
+    end
+
+    class SignedJWKS
+      def self.fetch!: (
+        String signed_jwks_uri,
+        untyped entity_jwks,
+        ?cache_key: String?,
+        ?cache_ttl: Integer?,
+        ?force_refresh: bool
+      ) -> Hash[String, untyped]
+
+      def initialize: (String signed_jwks_uri, untyped entity_jwks) -> void
+      def fetch_and_validate: () -> Hash[String, untyped]
+    end
+
+    class TrustChainResolver
+      def initialize: (
+        leaf_entity_id: String,
+        trust_anchors: Array[Hash[Symbol, untyped]],
+        ?max_chain_length: Integer,
+        ?timeout: Integer
+      ) -> void
+
+      def resolve!: () -> Array[Hash[Symbol, untyped]]
+    end
+
+    class MetadataPolicyMerger
+      def initialize: (trust_chain: Array[Hash[Symbol, untyped]]) -> void
+      def merge_policies: () -> Hash[String, untyped]
+      def apply_policies: (Hash[String, untyped] entity_metadata) -> Hash[String, untyped]
+      def merge_and_apply: (Hash[String, untyped] entity_metadata) -> Hash[String, untyped]
+    end
+  end
+
+  class FederationEndpoint
+    def self.configure: () { (FederationEndpoint::Configuration) -> void } -> FederationEndpoint::Configuration
+    def self.auto_configure: (
+      issuer: String,
+      ?signing_key: untyped,
+      ?encryption_key: untyped,
+      ?private_key: untyped,
+      ?jwks: Hash[String, untyped]?,
+      ?subject: String?,
+      ?entity_statement_path: String?,
+      ?entity_statement_url: String?,
+      ?metadata: Hash[String, untyped]?,
+      ?expiration_seconds: Integer?,
+      ?jwks_cache_ttl: Integer?,
+      ?auto_provision_keys: bool,
+      ?key_rotation_period: Integer?
+    ) -> FederationEndpoint::Configuration
+
+    def self.provision_jwks: (
+      ?signing_key: untyped,
+      ?encryption_key: untyped,
+      ?private_key: untyped,
+      ?entity_statement_path: String?,
+      ?issuer: String?,
+      ?subject: String?,
+      ?metadata: Hash[String, untyped]?,
+      ?entity_statement_path_provided: bool
+    ) -> Hash[String, untyped]?
+
+    def self.configuration: () -> FederationEndpoint::Configuration
+    def self.generate_entity_statement: () -> String
+    def self.generate_signed_jwks: () -> String
+    def self.current_jwks: () -> Hash[String, untyped]
+    def self.rack_app: () -> RackEndpoint
+    def self.mount_routes: (
+      untyped router,
+      ?entity_statement_path: String,
+      ?fetch_path: String,
+      ?jwks_path: String,
+      ?signed_jwks_path: String,
+      ?as: Symbol
+    ) -> void
+
+    def self.generate_fresh_keys: (
+      entity_statement_path: String,
+      ?issuer: String?,
+      ?subject: String?,
+      ?metadata: Hash[String, untyped]?,
+      ?keys_output_dir: String?
+    ) -> Hash[String, untyped]?
+
+    def self.rotate_keys_if_needed: (FederationEndpoint::Configuration config) -> void
+    def self.ensure_jwks_endpoints: (
+      Hash[String, untyped] metadata,
+      String issuer,
+      Symbol? entity_type
+    ) -> Hash[String, untyped]
+
+    def self.generate_subordinate_statement: (
+      subject_entity_id: String,
+      ?subject_metadata: Hash[String, untyped]?,
+      ?metadata_policy: Hash[String, untyped]?,
+      ?constraints: Hash[String, untyped]?,
+      ?source_endpoint: String?
+    ) -> String
+
+    def self.get_subordinate_statement: (String subject_entity_id) -> String?
+
+    class Configuration
+      attr_accessor issuer: String?
+      attr_accessor subject: String?
+      attr_accessor private_key: untyped
+      attr_accessor jwks: Hash[String, untyped]?
+      attr_accessor metadata: Hash[String, untyped]?
+      attr_accessor expiration_seconds: Integer
+      attr_accessor kid: String?
+      attr_accessor entity_type: Symbol
+      attr_accessor signing_key: untyped
+      attr_accessor encryption_key: untyped
+      attr_accessor auto_provision_keys: bool
+      attr_accessor entity_statement_path: String?
+      attr_accessor key_rotation_period: Integer?
+      attr_accessor current_jwks: Hash[String, untyped]?
+      attr_accessor current_jwks_proc: Proc?
+      attr_accessor signed_jwks_payload: Hash[String, untyped]?
+      attr_accessor signed_jwks_payload_proc: Proc?
+      attr_accessor signed_jwks_expiration_seconds: Integer
+      attr_accessor signed_jwks_signing_kid: String?
+      attr_accessor jwks_cache_ttl: Integer
+      attr_accessor subordinate_statements: Hash[String, Hash[Symbol, untyped]]?
+      attr_accessor subordinate_statements_proc: Proc?
+      attr_accessor authority_hints: Array[String]?
+
+      def initialize: () -> void
+    end
+  end
+end
+

data/sig/jwks.rbs

@@ -0,0 +1,63 @@
+module OmniauthOpenidFederation
+  module Jwks
+    module Fetch
+      def self.run: (
+        String jwks_uri,
+        ?entity_statement_keys: untyped,
+        ?cache_ttl: Integer?,
+        ?force_refresh: bool
+      ) -> Hash[String, untyped]
+
+      def self.fetch_jwks: (
+        String jwks_uri,
+        ?entity_statement_keys: untyped
+      ) -> Hash[String, untyped]
+    end
+
+    class Normalizer
+      def self.to_jwks_hash: (untyped jwks) -> Hash[String, Array[Hash[String, untyped]]]
+      def self.normalize_keys_array: (untyped keys) -> Hash[String, Array[Hash[String, untyped]]]
+    end
+
+    module Decode
+      def self.run: (
+        String encoded_jwt,
+        String jwks_uri,
+        ?retried: bool,
+        ?entity_statement_keys: untyped,
+        &Proc[Hash[String, untyped], untyped]
+      ) -> untyped
+
+      def self.jwt: (
+        String encoded_jwt,
+        String jwks_uri,
+        ?retried: bool,
+        ?entity_statement_keys: untyped
+      ) -> Array[Hash[String, untyped]]
+
+      def self.json_jwt: (
+        String encoded_jwt,
+        String jwks_uri,
+        ?retried: bool,
+        ?entity_statement_keys: untyped
+      ) -> untyped
+    end
+
+    class Selector
+      def self.current_keys: (untyped jwks) -> Hash[String, Array[Hash[String, untyped]]]
+      def self.all_keys: (untyped jwks) -> Hash[String, Array[Hash[String, untyped]]]
+      def self.signing_keys: (untyped jwks) -> Array[Hash[String, untyped]]
+      def self.encryption_keys: (untyped jwks) -> Array[Hash[String, untyped]]
+      def self.key_by_kid: (untyped jwks, String kid) -> Hash[String, untyped]?
+      def self.extract_keys_array: (untyped jwks) -> Array[Hash[String, untyped]]
+    end
+
+    class Rotate
+      def self.run: (
+        String jwks_uri,
+        ?entity_statement_path: String?
+      ) -> Hash[String, untyped]
+    end
+  end
+end
+

data/sig/omniauth_openid_federation.rbs

@@ -0,0 +1,254 @@
+module OmniauthOpenidFederation
+  VERSION: String
+
+  def self.configure: () { (Configuration) -> void } -> Configuration
+  def self.config: () -> Configuration
+  def self.rotate_jwks: (String jwks_uri, ?entity_statement_path: String?) -> Hash[String, untyped]
+
+  class Configuration
+    attr_accessor verify_ssl: bool
+    attr_accessor cache_ttl: Integer?
+    attr_accessor rotate_on_errors: bool
+    attr_accessor http_timeout: Integer
+    attr_accessor max_retries: Integer
+    attr_accessor retry_delay: Integer
+    attr_accessor http_options: Hash[Symbol, untyped] | Proc | nil
+    attr_accessor cache_adapter: untyped
+    attr_accessor root_path: String?
+    attr_accessor clock_skew_tolerance: Integer
+    attr_accessor instrumentation: Proc | untyped | nil
+
+    def self.config: () -> Configuration
+    def self.reset!: () -> void
+    def self.configure: () { (Configuration) -> void } -> Configuration
+    def initialize: () -> void
+  end
+
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class SecurityError < Error; end
+  class NetworkError < Error; end
+  class ValidationError < Error; end
+  class DecryptionError < SecurityError; end
+  class EncryptionError < SecurityError; end
+  class SignatureError < SecurityError; end
+  class FetchError < NetworkError; end
+  class KeyRelatedError < FetchError
+    def key_related_error?: () -> bool
+  end
+  class KeyRelatedValidationError < ValidationError
+    def key_related_error?: () -> bool
+  end
+
+  module Cache
+    def self.key_for_jwks: (String jwks_uri) -> String
+    def self.key_for_signed_jwks: (String signed_jwks_uri) -> String
+    def self.delete_jwks: (String jwks_uri) -> void
+    def self.delete_signed_jwks: (String signed_jwks_uri) -> void
+  end
+
+  module Constants
+    KEY_ROTATION_HTTP_CODES: Array[Integer]
+    REQUEST_OBJECT_EXPIRATION_SECONDS: Integer
+    MAX_RETRY_DELAY_SECONDS: Integer
+  end
+
+  module Utils
+    def self.to_indifferent_hash: (untyped hash) -> Hash[String, untyped] | ActiveSupport::HashWithIndifferentAccess
+    def self.sanitize_path: (String? path) -> String
+    def self.sanitize_uri: (String? uri) -> String
+    def self.build_endpoint_url: (String | URI issuer_uri, String endpoint_path) -> String
+    def self.build_entity_statement_url: (String | URI issuer_uri, ?entity_statement_endpoint: String?) -> String
+    def self.validate_file_path!: (String path, ?allowed_dirs: Array[String]?) -> String
+    def self.valid_jwt_format?: (String? str) -> bool
+    def self.extract_jwks_from_entity_statement: (String entity_statement_content) -> Hash[String, untyped]?
+    def self.rsa_key_to_jwk: (untyped key, ?use: String?) -> Hash[String, untyped]
+  end
+
+  module RateLimiter
+    def self.allow?: (String key, ?max_requests: Integer, ?window: Integer) -> bool
+    def self.reset!: (String key) -> void
+  end
+
+  class HttpClient
+    def self.get: (String uri, ?timeout: Integer, ?max_retries: Integer, ?retry_delay: Integer) -> untyped
+  end
+
+  class Logger
+    def self.logger: () -> untyped
+    def self.logger=: (untyped logger) -> void
+    def self.debug: (String message) -> void
+    def self.info: (String message) -> void
+    def self.warn: (String message) -> void
+    def self.error: (String message) -> void
+  end
+
+  class Jws
+    attr_accessor private_key: untyped
+    attr_accessor state: String?
+    attr_accessor nonce: String?
+    attr_accessor ftn_spname: String?
+
+    def initialize: (
+      client_id: String,
+      redirect_uri: String,
+      ?scope: String,
+      ?issuer: String?,
+      ?audience: String?,
+      ?state: String?,
+      ?nonce: String?,
+      ?response_type: String,
+      ?response_mode: String?,
+      ?login_hint: String?,
+      ?ui_locales: String?,
+      ?claims_locales: String?,
+      ?prompt: String?,
+      ?hd: String?,
+      ?acr_values: String?,
+      ?extra_params: Hash[Symbol, untyped],
+      ?private_key: untyped,
+      ?entity_statement_path: String?
+    ) -> void
+
+    def add_claim: (Symbol key, untyped value) -> void
+    def sign: (?provider_metadata: Hash[String, untyped]?, ?always_encrypt: bool) -> String
+  end
+
+  class EntityStatementReader
+    def self.fetch_keys: (?entity_statement_path: String?) -> Array[untyped]
+    def self.parse_metadata: (?entity_statement_path: String?) -> Hash[Symbol, untyped]?
+    def self.validate_fingerprint: (
+      String entity_statement_content,
+      String expected_fingerprint
+    ) -> bool
+  end
+
+  class EndpointResolver
+    def self.resolve: (
+      ?entity_statement_path: String?,
+      ?config: Hash[Symbol, String?]
+    ) -> Hash[Symbol, String?]
+
+    def self.validate_and_build_audience: (
+      Hash[Symbol, String?] endpoints,
+      ?issuer_uri: URI
+    ) -> Hash[Symbol, String?]
+  end
+
+  class KeyExtractor
+    def self.extract_signing_key: (
+      ?jwks: Hash[String, untyped] | Array[Hash[String, untyped]] | nil,
+      ?metadata: Hash[String, untyped]?,
+      ?private_key: untyped
+    ) -> untyped
+
+    def self.extract_encryption_key: (
+      ?jwks: Hash[String, untyped] | Array[Hash[String, untyped]] | nil,
+      ?metadata: Hash[String, untyped]?,
+      ?private_key: untyped
+    ) -> untyped
+  end
+
+  class RackEndpoint
+    def call: (Hash[String, untyped] env) -> Array[Integer, Hash[String, String], Array[String]]
+  end
+
+  module TasksHelper
+    def self.resolve_path: (String file_path) -> String
+    def self.fetch_entity_statement: (
+      url: String,
+      output_file: String,
+      ?fingerprint: String?
+    ) -> Hash[Symbol, untyped]
+
+    def self.validate_entity_statement: (
+      file_path: String,
+      ?fingerprint: String?
+    ) -> Hash[Symbol, untyped]
+
+    def self.parse_entity_statement: (String file_path) -> Hash[String, untyped]
+
+    def self.fetch_jwks: (
+      jwks_uri: String,
+      output_file: String
+    ) -> Hash[Symbol, untyped]
+
+    def self.prepare_client_keys: (
+      ?key_type: String,
+      ?output_dir: String
+    ) -> Hash[Symbol, untyped]
+  end
+
+  module StringHelpers
+    def self.present?: (untyped value) -> bool
+    def self.blank?: (untyped value) -> bool
+  end
+
+  module Validators
+    def self.validate_private_key!: (untyped private_key) -> void
+    def self.normalize_hash: (untyped hash) -> Hash[Symbol, untyped]
+  end
+
+  module Instrumentation
+    EVENT_CSRF_DETECTED: String
+    EVENT_SIGNATURE_VERIFICATION_FAILED: String
+    EVENT_DECRYPTION_FAILED: String
+    EVENT_TOKEN_VALIDATION_FAILED: String
+    EVENT_KEY_ROTATION_DETECTED: String
+    EVENT_KID_NOT_FOUND: String
+    EVENT_ENTITY_STATEMENT_VALIDATION_FAILED: String
+    EVENT_FINGERPRINT_MISMATCH: String
+    EVENT_TRUST_CHAIN_VALIDATION_FAILED: String
+    EVENT_ENDPOINT_MISMATCH: String
+    EVENT_UNEXPECTED_AUTHENTICATION_BREAK: String
+    EVENT_STATE_MISMATCH: String
+    EVENT_MISSING_REQUIRED_CLAIMS: String
+    EVENT_AUDIENCE_MISMATCH: String
+    EVENT_ISSUER_MISMATCH: String
+    EVENT_EXPIRED_TOKEN: String
+    EVENT_INVALID_NONCE: String
+
+    def self.notify: (
+      String event,
+      ?data: Hash[Symbol, untyped],
+      ?severity: Symbol
+    ) -> void
+
+    def self.notify_csrf_detected: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_signature_verification_failed: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_decryption_failed: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_token_validation_failed: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_key_rotation_detected: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_kid_not_found: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_entity_statement_validation_failed: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_fingerprint_mismatch: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_trust_chain_validation_failed: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_endpoint_mismatch: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_unexpected_authentication_break: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_state_mismatch: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_missing_required_claims: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_audience_mismatch: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_issuer_mismatch: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_expired_token: (?Hash[Symbol, untyped] data) -> void
+    def self.notify_invalid_nonce: (?Hash[Symbol, untyped] data) -> void
+  end
+
+  class CacheAdapter
+    def self.available?: () -> bool
+    def self.get: (String key) -> untyped
+    def self.set: (String key, untyped value, ?ttl: Integer) -> void
+    def self.delete: (String key) -> void
+  end
+
+  module Jwks
+    class Cache
+      attr_reader jwks_source: untyped
+      attr_reader timeout_sec: Integer
+      attr_reader cache_last_update: Integer
+
+      def initialize: (untyped jwks_source, ?timeout_sec: Integer) -> void
+      def call: (?Hash[Symbol, untyped] options) -> Array[Hash[String, untyped]]
+      def clear!: () -> void
+    end
+  end
+end

data/sig/strategy.rbs

@@ -0,0 +1,60 @@
+module OmniAuth
+  module Strategies
+    class OpenIDFederation < OmniAuth::Strategies::OAuth2
+      def client: () -> untyped
+      def oidc_client: () -> untyped
+      def request_phase: () -> untyped
+      def callback_phase: () -> untyped
+      def auth_hash: () -> OmniAuth::AuthHash
+      def authorize_uri: () -> String
+      def raw_info: () -> Hash[String, untyped]
+      def client_jwk_signing_key: () -> untyped
+      def options: () -> untyped
+      def exchange_authorization_code: (String authorization_code) -> untyped
+      def new_state: () -> String
+      def new_nonce: () -> String
+      def resolve_endpoints_from_metadata: (Hash[Symbol, untyped] client_options_hash) -> Hash[Symbol, String?]
+      def resolve_issuer_from_metadata: () -> String?
+      def resolve_audience: (Hash[Symbol, untyped] client_options_hash, String? resolved_issuer) -> String
+      def resolve_jwks_for_validation: (Hash[Symbol, untyped] normalized_options) -> Hash[String, untyped]
+      def resolve_jwks_for_validation_with_kid: (Hash[Symbol, untyped] normalized_options, String kid) -> Hash[String, untyped]
+      def resolve_jwks_uri: (Hash[Symbol, untyped] normalized_options) -> String?
+      def build_base_url: (Hash[Symbol, untyped] client_options_hash) -> String
+      def build_endpoint: (String base_url, String path) -> String
+      def decode_id_token: (String id_token) -> Hash[String, untyped]
+      def encrypted_token?: (String token) -> bool
+      def decode_userinfo: (untyped userinfo) -> Hash[String, untyped]
+      def load_provider_entity_statement: () -> Hash[Symbol, untyped]?
+      def fetch_and_cache_entity_statement: (String url, ?fingerprint: String?) -> Hash[Symbol, untyped]?
+      def resolve_endpoints_from_trust_chain: (String issuer_entity_id, Hash[Symbol, untyped] client_options_hash) -> Hash[Symbol, String?]
+      def extract_metadata_from_parsed: (Hash[Symbol, untyped] parsed) -> Hash[Symbol, untyped]?
+      def normalize_trust_anchors: (untyped trust_anchors) -> Array[Hash[Symbol, untyped]]
+      def is_entity_id?: (String str) -> bool
+      def resolve_entity_statement_path: (String path) -> String
+      def load_metadata_for_key_extraction: () -> Hash[Symbol, untyped]?
+      def load_client_entity_statement: (?entity_statement_path: String?, ?entity_statement_url: String?) -> Hash[Symbol, untyped]?
+      def load_client_entity_statement_from_file: (String entity_statement_path) -> Hash[Symbol, untyped]?
+      def load_client_entity_statement_from_url: (String entity_statement_url) -> Hash[Symbol, untyped]?
+      def extract_client_jwk_signing_key: () -> untyped
+      def extract_entity_identifier_from_statement: (Hash[Symbol, untyped] entity_statement, String? configured_identifier) -> String?
+      def load_provider_metadata_for_encryption: () -> Hash[String, untyped]?
+      def combine_acr_values: (?configured_acr: String?, ?request_acr: String?) -> String?
+      def normalize_acr_values: (untyped acr_values) -> String?
+      def fetch_jwks: (String jwks_uri) -> Hash[String, untyped]
+    end
+
+    OpenidFederation: singleton(OpenIDFederation)
+  end
+end
+
+module OpenIDConnect
+  class AccessToken
+    def resource_request: () { () -> untyped } -> untyped
+    def get_strategy_options: () -> Hash[Symbol, untyped]
+    def extract_encryption_key_for_decryption: () -> untyped
+    def fetch_signed_jwks: (Hash[Symbol, untyped] strategy_options) -> Hash[String, untyped]?
+    def load_entity_statement_keys_for_jwks_validation: (Hash[Symbol, untyped] strategy_options) -> Array[untyped]
+    def resolve_jwks_uri_from_entity_statement: (Hash[Symbol, untyped] strategy_options) -> String?
+  end
+end
+