keycloak_ruby 0.1.0

data/sig/keycloak_ruby.rbs

@@ -0,0 +1,656 @@
+# Module for interacting with Keycloak
+module KeycloakRuby
+  self.@config: untyped
+
+  # Returns the singleton configuration object. The configuration is
+  # initialized on first access and validated immediately.
+  #
+  # @return [KeycloakRuby::Config] the configuration object
+  def self.config: () -> untyped
+
+  # Yields the configuration object for block-based configuration.
+  # Validates the configuration after the block executes.
+  #
+  # @yield [KeycloakRuby::Config] the configuration object
+  # @raise [ConfigurationError] if configuration is invalid
+  def self.configure: () { (untyped) -> untyped } -> untyped
+
+  VERSION: untyped
+end
+
+# lib/keycloak_ruby/user.rb
+module KeycloakRuby
+  # User-related operations for interacting with Keycloak.
+  # This class provides a simple interface for creating, deleting, and finding users in Keycloak.
+  class User
+    self.@client: untyped
+
+    # Creates a new user in Keycloak.
+    #
+    # @param user_attrs [Hash] A hash of user attributes (e.g., :username, :email, :password, :temporary).
+    # @return [Hash] The created user's data.
+    # @raise [KeycloakRuby::Error] If the user creation fails.
+    def self.create: (?::Hash[untyped, untyped] user_attrs) -> untyped
+
+    # Deletes users from Keycloak based on a search string.
+    #
+    # @param search_string [String] A string to search for users (e.g., username, email, etc.).
+    # @return [void]
+    # @raise [KeycloakRuby::Error] If any user deletion fails.
+    def self.delete: (untyped search_string) -> untyped
+
+    # Deletes a user from Keycloak by ID.
+    #
+    # @param user_id [String] The ID of the user to delete.
+    # @return [void]
+    # @raise [KeycloakRuby::Error] If the deletion fails.
+    def self.delete_by_id: (untyped user_id) -> untyped
+
+    # Finds users in Keycloak based on a search string.
+    #
+    # @param search_string [String] A string to search for users (e.g., username, email, etc.).
+    # @return [Array<Hash>] An array of user objects (hashes) matching the search criteria.
+    # @raise [KeycloakRuby::Error] If the search fails.
+    def self.find: (untyped search_string) -> untyped
+
+    private
+
+    # Provides a singleton instance of the KeycloakRuby::Client.
+    #
+    # @return [KeycloakRuby::Client] The client instance used for making API requests.
+    def self.client: () -> untyped
+  end
+end
+
+module KeycloakRuby
+  # Responsible for performing HTTP requests with HTTParty
+  # and validating the response. This class helps to reduce
+  # FeatureEnvy and keep the Client code cleaner.
+  # :reek:FeatureEnvy
+  class RequestPerformer
+    @config: untyped
+
+    def initialize: (untyped config) -> void
+
+    # Executes an HTTP request and verifies the response code.
+    #
+    # @param request_params [KeycloakRuby::RequestParams] - an object containing
+    #   :http_method, :url, :headers, :body, :success_codes, :error_class, :error_message
+    #
+    # @return [HTTParty::Response] The HTTParty response object on success.
+    # @raise [request_params.error_class] If the response code is not in success_codes
+    #   or HTTParty raises an error.
+    def call: (untyped request_params) -> untyped
+
+    private
+
+    # Safe validation: returns true/false
+    def verify_response: (untyped response, untyped request_params) -> untyped
+
+    # Bang version that raises an error on invalid response
+    def verify_response!: (untyped response, untyped request_params) -> (nil | untyped)
+  end
+end
+
+# keycloak_ruby/testing/keycloak_helpers.rb
+# :reek:UtilityFunction :reek:ControlParameter :reek:ManualDispatch :reek:BooleanParameter :reek:LongParameterList
+module KeycloakRuby
+  module Testing
+    # Helper module for tests with Keycloak
+    module KeycloakHelpers
+      self.@keycloak_users: untyped
+
+      # Combines both sign-in approaches with automatic detection of test type
+      def sign_in: (untyped user, ?test_type: untyped) -> untyped
+
+      # Мокирует авторизацию в request-тестах, подставляя указанного пользователя в current_user.
+      # Нужно, так как в request-тестах нет прямого доступа к сессиям и внешним сервисам авторизации.
+      def mock_token_service: (untyped user) -> untyped
+
+      def create_keycloak_user: (username: untyped, email: untyped, password: untyped, temporary: untyped) -> untyped
+
+      # Delete all users from Keycloak
+      def self.delete_all_keycloak_users: () -> untyped
+
+      def self.track_keycloak_user: (untyped user_id) -> untyped
+
+      def self.cleanup_keycloak_users: () -> (nil | untyped)
+
+      private
+
+      def mock_keycloak_login: (untyped user, ?use_capybara: bool) -> untyped
+
+      def capybara_login: () -> untyped
+
+      def generate_fake_tokens: (untyped user) -> untyped
+
+      def store_session: (untyped credentials) -> untyped
+
+      def rspec_auto_detect_test_type: () -> (:request | :feature | :controller)
+
+      def auto_detect_test_type: () -> (untyped | :feature)
+    end
+  end
+end
+
+module Minitest
+  class Test
+    include KeycloakRuby::Testing::KeycloakHelpers
+  end
+end
+
+module KeycloakRuby
+  # Validates Keycloak API responses with both safe and strict modes
+  #
+  # Provides two validation approaches:
+  # 1. Safe validation (#validate) - returns boolean
+  # 2. Strict validation (#validate!) - raises detailed exceptions
+  #
+  # @example Safe validation
+  #   validator = ResponseValidator.new(response)
+  #   if validator.validate
+  #     # proceed with valid response
+  #   else
+  #     # handle invalid response
+  #   end
+  #
+  # @example Strict validation
+  #   begin
+  #     data = ResponseValidator.new(response).validate!
+  #     # use validated data
+  #   rescue KeycloakRuby::Errors::TokenRefreshFailed => e
+  #     # handle error
+  #   end
+  class ResponseValidator
+    @response: untyped
+
+    @data: untyped
+
+    # Initialize with the HTTP response
+    # @param response [HTTP::Response] The raw HTTP response from Keycloak
+    def initialize: (untyped response) -> void
+
+    # Safe validation - returns boolean instead of raising exceptions
+    # @return [Boolean] true if response is valid, false otherwise
+    def validate: () -> (false | untyped)
+
+    # Strict validation - raises exceptions for invalid responses
+    # @return [Hash] Parsed response data if valid
+    # @raise [KeycloakRuby::Errors::TokenRefreshFailed] if validation fails
+    def validate!: () -> untyped
+
+    private
+
+    # Parses JSON response body, returns empty hash on failure
+    # @return [Hash]
+    def parse_response_body: () -> untyped
+
+    # Checks if HTTP status indicates success
+    # @return [Boolean]
+    def valid_http_status?: () -> untyped
+
+    # Checks for OAuth2 "invalid_grant" error
+    # @return [Boolean]
+    def invalid_grant?: () -> untyped
+
+    # Checks for any error in response
+    # @return [Boolean]
+    def error_present?: () -> untyped
+
+    # Verifies access token presence
+    # @return [Boolean]
+    def access_token_present?: () -> untyped
+
+    # Raises appropriate validation error based on failure reason
+    # @raise [KeycloakRuby::Errors::TokenRefreshFailed]
+    def raise_validation_error: () -> untyped
+
+    # Extracts error message from response
+    # @return [String]
+    def extract_error_message: () -> (untyped | untyped | "See response body for details")
+  end
+end
+
+# lib/keycloak_ruby/config.rb
+module KeycloakRuby
+  # Configuration class for Keycloak Ruby gem.
+  #
+  # Handles loading and validation of Keycloak configuration from either:
+  # - A YAML file (default: config/keycloak.yml)
+  # - Direct attribute assignment
+  #
+  # == Example YAML Configuration
+  #
+  #   development:
+  #     keycloak_url: "https://keycloak.example.com"
+  #     app_host: "http://localhost:3000"
+  #     realm: "my-realm"
+  #     oauth_client_id: "my-client"
+  #     oauth_client_secret: "secret"
+  #
+  # == Example Programmatic Configuration
+  #
+  #   config = KeycloakRuby::Config.new
+  #   config.keycloak_url = "https://keycloak.example.com"
+  #   config.realm = "my-realm"
+  #   # ... etc
+  # :reek:MissingSafeMethod
+  class Config
+    @config_path: untyped
+
+    # Default path to configuration file (Rails.root/config/keycloak.yml)
+    DEFAULT_CONFIG_PATH: untyped
+
+    REQUIRED_ATTRIBUTES: ::Array[:keycloak_url | :app_host | :realm | :oauth_client_id | :oauth_client_secret]
+
+    # :reek:Attribute
+    attr_accessor keycloak_url: untyped
+
+    # :reek:Attribute
+    attr_accessor app_host: untyped
+
+    # :reek:Attribute
+    attr_accessor realm: untyped
+
+    # :reek:Attribute
+    attr_accessor admin_client_id: untyped
+
+    # :reek:Attribute
+    attr_accessor admin_client_secret: untyped
+
+    # :reek:Attribute
+    attr_accessor oauth_client_id: untyped
+
+    # :reek:Attribute
+    attr_accessor oauth_client_secret: untyped
+
+    attr_reader config_path: untyped
+
+    # Initialize configuration, optionally loading from YAML file
+    #
+    # @param config_path [String] Path to YAML config file (default: config/keycloak.yml)
+    #
+    #
+    def initialize: (?untyped config_path) -> void
+
+    def validate!: () -> untyped
+
+    def realm_url: () -> ::String
+
+    def redirect_url: () -> ::String
+
+    def logout_url: () -> ::String
+
+    def token_url: () -> ::String
+
+    private
+
+    # Loads configuration from YAML file if it exists
+    # :reek:ManualDispatch
+    def load_config: () -> (nil | untyped)
+
+    def load_yaml_file: () -> untyped
+
+    def current_env: () -> untyped
+
+    def apply_config: (untyped config_hash) -> untyped
+  end
+end
+
+module KeycloakRuby
+  # Include test methods
+  module Testing
+    def self.included: (untyped base) -> untyped
+  end
+end
+
+# lib/keycloak_ruby/request_params.rb
+module KeycloakRuby
+  # A small, typed struct for request parameters
+  RequestParams: untyped
+end
+
+# lib/keycloak_ruby/errors.rb
+module KeycloakRuby
+  # Namespace for all KeycloakRuby specific errors
+  # Follows a hierarchical structure for better error handling
+  module Errors
+    # Base error class for all KeycloakRuby errors
+    # All custom errors inherit from this class
+    class Error < StandardError
+    end
+
+    # Raised when there's an issue with gem configuration
+    class ConfigurationError < Error
+    end
+
+    # Base class for authentication failures
+    class AuthenticationError < Error
+    end
+
+    # Raised when user credentials are invalid
+    class InvalidCredentials < AuthenticationError
+    end
+
+    # Raised when user account is not found
+    class UserNotFound < AuthenticationError
+    end
+
+    # Raised when account is temporarily locked
+    class AccountLocked < AuthenticationError
+    end
+
+    # Raised when user creation fails
+    class UserCreationError < Error
+    end
+
+    # Raised when user update fails
+    class UserUpdateError < Error
+    end
+
+    # Raised when user deletion fails
+    class UserDeletionError < Error
+    end
+
+    # Base class for all token-related errors
+    class TokenError < Error
+    end
+
+    # Raised when token has expired +
+    class TokenExpired < TokenError
+    end
+
+    # Raised when token is invalid (malformed, wrong signature, etc.)
+    class TokenInvalid < TokenError
+    end
+
+    # Raised when token refresh fails
+    class TokenRefreshFailed < TokenError
+    end
+
+    # Raised when token verification fails
+    class TokenVerificationFailed < TokenError
+    end
+
+    # Raised when API request fails
+    class APIError < Error
+    end
+
+    # Raised when receiving 4xx responses from Keycloak
+    class ClientError < APIError
+    end
+
+    # Raised when receiving 5xx responses from Keycloak
+    class ServerError < APIError
+    end
+
+    # Raised when connection to Keycloak fails
+    class ConnectionError < APIError
+    end
+  end
+end
+
+# lib/keycloak_ruby/token_service.rb
+# :reek:FeatureEnvy
+module KeycloakRuby
+  # Service for check and refresh jwt tokens
+  class TokenService
+    @session: untyped
+
+    @config: untyped
+
+    @refresh_mutex: untyped
+
+    @fetch_jwks: untyped
+
+    @issuer_url: untyped
+
+    def initialize: (untyped session, ?untyped config) -> void
+
+    # Finds user by token claims
+    # @return [User, nil]
+    def find_user: () -> (nil | untyped)
+
+    # Store token
+    def store_tokens: (untyped data) -> untyped
+
+    def clear_tokens: () -> untyped
+
+    private
+
+    # It's necessary, because omniauth return request.env["omniauth.auth"] as 'token', not 'access_token'
+    def extract_access_token: (untyped data) -> untyped
+
+    # Gets current token or attempts refresh if expired
+    # @return [Hash, nil] Decoded token claims
+    def current_token: () -> untyped
+
+    # Decodes JWT token
+    # @raise [Errors::TokenExpired, Errors::TokenInvalid]
+    def decode_token: (untyped token) -> untyped
+
+    def fetch_jwks: () -> untyped
+
+    # Attempts to refresh the current token
+    def refresh_current_token: () -> untyped
+
+    # JWT decoding options with JWKS
+    def jwt_decode_options: () -> { algorithms: ::Array["RS256"], verify_iss: true, iss: untyped, aud: untyped, verify_expiration: true, jwks: untyped }
+
+    # Constructs issuer URL from configuration
+    def issuer_url: () -> untyped
+  end
+end
+
+# lib/keycloak_ruby/token_refresher.rb`
+module KeycloakRuby
+  # Handles OAuth2 refresh token flow with Keycloak
+  #
+  # Responsible for:
+  # - Executing refresh token requests
+  # - Validating responses
+  # - Managing refresh failures
+  #
+  # @example Basic usage
+  #   refresher = TokenRefresher.new(session, config)
+  #   new_tokens = refresher.call
+  #
+  # @example With error handling
+  #   begin
+  #     refresher.call
+  #   rescue KeycloakRuby::Errors::TokenRefreshFailed => e
+  #     # Handle token refresh failure (e.g., redirect to login)
+  #   end
+  class TokenRefresher
+    @session: untyped
+
+    @config: untyped
+
+    def initialize: (untyped session, untyped config) -> void
+
+    # Main entry point - refreshes the token
+    # @return [Hash] New token data if successful
+    # @raise [KeycloakRuby::Errors::TokenRefreshFailed] if refresh fails
+    def call: () -> untyped
+
+    private
+
+    def refresh_token_flow: () -> untyped
+
+    def request_refresh: () -> untyped
+
+    def validate_response: (untyped response) -> untyped
+
+    def handle_http_error: (untyped exception) -> untyped
+
+    # :reek:FeatureEnvy
+    def handle_failed_validation: (untyped response) -> untyped
+
+    def refresh_params: () -> { grant_type: "refresh_token", client_id: untyped, client_secret: untyped, refresh_token: untyped }
+
+    def headers: () -> { "Content-Type" => "application/x-www-form-urlencoded", "Accept" => "application/json", "User-Agent" => ::String }
+
+    def log_refresh_attempt: () -> untyped
+
+    def log_successful_refresh: () -> untyped
+  end
+end
+
+# lib/keycloak_ruby/client.rb
+module KeycloakRuby
+  # Client for interacting with Keycloak (create, delete, and find users, etc.).
+  # rubocop:disable Metrics/ClassLength
+  # rubocop:disable Metrics/MethodLength
+  # :reek:TooManyMethods
+  class Client
+    @config: untyped
+
+    @request_performer: untyped
+
+    def initialize: (?untyped config) -> void
+
+    # Authenticates a user with Keycloak and returns token data upon success.
+    #
+    # @param username [String] The user's username or email.
+    # @param password [String] The user's password.
+    # @return [Hash] The token data (access_token, refresh_token, id_token, etc.).
+    # @raise [KeycloakRuby::Errors::InvalidCredentials] If authentication fails.
+    def authenticate_user: (username: untyped, password: untyped) -> untyped
+
+    # Creates a user in Keycloak and returns the newly created user's data.
+    #
+    # @param user_attrs [Hash] A hash of user attributes. Must contain:
+    #   :username, :email, :password, :temporary
+    # @option user_attrs [String] :username The username for the new user.
+    # @option user_attrs [String] :email The user's email.
+    # @option user_attrs [String] :password The initial password.
+    # @option user_attrs [Boolean] :temporary Whether to force a password update on first login.
+    #
+    # @raise [KeycloakRuby::Errors::UserCreationError] If user creation fails.
+    # @return [Hash] The newly created user's data.
+    def create_user: (?::Hash[untyped, untyped] user_attrs) -> untyped
+
+    # Deletes all users that match the provided search string (e.g., username, email).
+    #
+    # @param search_string [String] The search criteria for finding users in Keycloak.
+    # @raise [KeycloakRuby::Errors::UserDeletionError] If any user deletion fails.
+    def delete_users: (untyped search_string) -> untyped
+
+    # Deletes a single user by ID in Keycloak.
+    #
+    # @param user_id [String] The ID of the user to delete.
+    # @raise [KeycloakRuby::Errors::UserDeletionError] If the deletion fails.
+    def delete_user_by_id: (untyped user_id) -> untyped
+
+    # Finds all users in Keycloak that match the given search string.
+    #
+    # @param search [String] The search query (e.g., part of username or email).
+    # @return [Array<Hash>] An array of user objects.
+    # @raise [KeycloakRuby::Errors::APIError] If the request fails.
+    def find_users: (untyped search) -> untyped
+
+    # Updates the redirect URIs for a specific client in Keycloak.
+    #
+    # @param client_id [String] The client ID in Keycloak.
+    # @param redirect_uris [Array<String>] A list of valid redirect URIs for this client.
+    # @raise [KeycloakRuby::Errors::ConnectionError] If the update request fails.
+    def update_client_redirect_uris: (client_id: untyped, redirect_uris: untyped) -> untyped
+
+    private
+
+    def build_auth_body: (untyped username, untyped password) -> { client_id: untyped, client_secret: untyped, username: untyped, password: untyped, grant_type: "password" }
+
+    def build_user_data: (untyped attrs) -> { username: untyped, email: untyped, enabled: true, credentials: ::Array[{ type: "password", value: untyped, temporary: untyped }] }
+
+    # Builds RequestParams and passes them to the RequestPerformer.
+    def http_request: (?::Hash[untyped, untyped] options) -> untyped
+
+    def build_request_params: (untyped opts) -> untyped
+
+    # Retrieves client details by its "clientId".
+    #
+    # @param client_id [String] The "clientId" in Keycloak.
+    # @return [Hash] The client details.
+    # @raise [KeycloakRuby::Errors::ClientError] If no matching client is found or the request fails.
+    def find_client_by_id: (untyped client_id) -> untyped
+
+    # Performs a PUT request to update the redirect URIs for a given client in Keycloak.
+    #
+    # @param client_id [String] The internal Keycloak client ID.
+    # @param redirect_uris [Array<String>] List of valid redirect URIs for this client.
+    # @raise [KeycloakRuby::Errors::ConnectionError] If the update request fails.
+    def update_redirect_uris_for: (untyped client_id, untyped redirect_uris) -> untyped
+
+    # Fetches a user by ID from Keycloak.
+    #
+    # @param user_id [String] The user's ID in Keycloak.
+    # @return [Hash] The Keycloak user data.
+    # @raise [KeycloakRuby::Errors::UserNotFound] If the user cannot be found or the request fails.
+    def fetch_user: (untyped user_id) -> untyped
+
+    # Retrieves the admin token used to authenticate calls to the Keycloak Admin API.
+    #
+    # @return [String] The admin access token.
+    # @raise [KeycloakRuby::Errors::TokenVerificationFailed] If the token request fails.
+    def admin_token: () -> untyped
+
+    # Returns a set of default headers for requests requiring the admin token.
+    #
+    # @return [Hash] A headers Hash including Authorization and Content-Type.
+    def default_headers: () -> { "Authorization" => ::String, "Content-Type" => "application/json" }
+  end
+end
+
+# lib/keycloak_ruby/version.rb
+# Module for interacting with Keycloak
+module KeycloakRuby
+  # Version module following Semantic Versioning 2.0 guidelines
+  # Provides detailed version information and helper methods
+  #
+  # @example Getting version information
+  #   KeycloakRuby::Version::VERSION      # => "0.1.0"
+  #   KeycloakRuby::Version.to_a          # => [0, 1, 0]
+  #   KeycloakRuby::Version.to_h          # => { major: 0, minor: 1, patch: 0, pre: nil }
+  #   KeycloakRuby.version                # => "0.1.0"
+  #
+  # @example Checking version
+  #   KeycloakRuby::Version >= '0.1.0'    # => true
+  # Module for work with Version
+  module Version
+    # Major version number (incompatible API changes)
+    MAJOR: 0
+
+    # Minor version number (backwards-compatible functionality)
+    MINOR: 1
+
+    # Patch version number (backwards-compatible bug fixes)
+    PATCH: 0
+
+    # Pre-release version (nil for stable releases)
+    PRE: nil
+
+    # Full version string
+    VERSION: untyped
+
+    # Returns version components as an array
+    # @return [Array<Integer, Integer, Integer, String|nil>]
+    def self.to_a: () -> ::Array[untyped]
+
+    # Returns version components as a hash
+    # @return [Hash<Symbol, Integer|String|nil>]
+    def self.to_h: () -> { major: untyped, minor: untyped, patch: untyped, pre: untyped }
+
+    # Compares version with another version string
+    # @param version_string [String] version to compare with (e.g., "1.2.3")
+    # @return [Boolean]
+    def self.>=: (untyped version_string) -> untyped
+
+    # Returns the full version string
+    # @return [String]
+    def self.to_s: () -> untyped
+  end
+
+  # Returns the current gem version
+  # @return [String]
+  def self.version: () -> untyped
+end