securial 1.0.1 → 1.0.3

data/lib/securial/error.rb

@@ -1,9 +1,39 @@
+# Requires all error classes used in the Securial framework.
+#
+# This file serves as the central error management system for Securial,
+# loading all specialized error types and establishing the Error namespace.
+# Each error type extends from BaseSecurialError and provides specific
+# error handling for different parts of the framework.
+#
+# @example Accessing a specific error type
+#   begin
+#     # Some operation that might fail
+#   rescue Securial::Error::Auth::TokenDecodeError => e
+#     # Handle token decoding errors
+#   rescue Securial::Error::Config::ValidationError => e
+#     # Handle configuration validation errors
+#   rescue Securial::Error::BaseError => e
+#     # Handle any other Securial errors
+#   end
+#
 require "securial/error/base_securial_error"
 require "securial/error/config"
 require "securial/error/auth"
 
 module Securial
-  module Error
-    # This serves as a namespace for all Securial errors.
-  end
+  # Namespace for all Securial-specific errors and exceptions.
+  #
+  # The Error module contains specialized error classes for different
+  # components of the Securial framework, organized into submodules
+  # for better categorization:
+  #
+  # - {BaseError} - Base class for all Securial errors
+  # - {Config} - Configuration-related errors
+  # - {Auth} - Authentication and authorization errors
+  #
+  # @see Securial::Error::BaseError
+  # @see Securial::Error::Config
+  # @see Securial::Error::Auth
+  #
+  module Error; end
 end

data/lib/securial/helpers/key_transformer.rb

@@ -1,8 +1,56 @@
+# @title Securial Key Transformer Helpers
+#
+# Key transformation utilities for API response formatting in the Securial framework.
+#
+# This module provides utilities for transforming hash keys between different
+# naming conventions (snake_case, camelCase, PascalCase) to ensure API responses
+# follow consistent formatting standards regardless of Ruby's internal conventions.
+#
+# @example Converting keys to camelCase
+#   data = { user_name: "john", email_address: "john@example.com" }
+#   transformed = KeyTransformer.deep_transform_keys(data) { |key| KeyTransformer.camelize(key, :lowerCamelCase) }
+#   # => { userName: "john", emailAddress: "john@example.com" }
+#
+# @example Converting nested structures
+#   nested = { user: { first_name: "John", last_name: "Doe" } }
+#   camelized = KeyTransformer.deep_transform_keys(nested) { |key| KeyTransformer.camelize(key, :lowerCamelCase) }
+#   # => { user: { firstName: "John", lastName: "Doe" } }
+#
 module Securial
   module Helpers
+    # Transforms hash keys between different naming conventions.
+    #
+    # This module provides methods to convert between snake_case (Ruby convention),
+    # camelCase (JavaScript convention), and PascalCase (C# convention) for API
+    # response formatting. It supports deep transformation of nested structures.
+    #
     module KeyTransformer
       extend self
 
+      # Converts a string to camelCase or PascalCase format.
+      #
+      # Transforms snake_case strings into camelCase variants based on the
+      # specified format. Useful for converting Ruby hash keys to JavaScript
+      # or other language conventions.
+      #
+      # @param [String, Symbol] str The string to transform
+      # @param [Symbol] format The target camelCase format
+      # @option format [Symbol] :lowerCamelCase Converts to lowerCamelCase (firstName)
+      # @option format [Symbol] :UpperCamelCase Converts to PascalCase (FirstName)
+      # @return [String] The transformed string, or original if format not recognized
+      #
+      # @example Converting to lowerCamelCase
+      #   KeyTransformer.camelize("user_name", :lowerCamelCase)
+      #   # => "userName"
+      #
+      # @example Converting to PascalCase
+      #   KeyTransformer.camelize("email_address", :UpperCamelCase)
+      #   # => "EmailAddress"
+      #
+      # @example Unrecognized format returns original
+      #   KeyTransformer.camelize("user_name", :snake_case)
+      #   # => "user_name"
+      #
       def camelize(str, format)
         case format
         when :lowerCamelCase
@@ -14,10 +62,68 @@ module Securial
         end
       end
 
+      # Converts a camelCase or PascalCase string to snake_case.
+      #
+      # Transforms camelCase or PascalCase strings back to Ruby's snake_case
+      # convention. Useful for converting API input keys to Ruby conventions.
+      #
+      # @param [String, Symbol] str The string to transform
+      # @return [String] The snake_case version of the string
+      #
+      # @example Converting from camelCase
+      #   KeyTransformer.underscore("userName")
+      #   # => "user_name"
+      #
+      # @example Converting from PascalCase
+      #   KeyTransformer.underscore("EmailAddress")
+      #   # => "email_address"
+      #
       def self.underscore(str)
         str.to_s.underscore
       end
 
+      # Recursively transforms all keys in a nested data structure.
+      #
+      # Applies a key transformation block to all hash keys in a deeply nested
+      # structure containing hashes, arrays, and other objects. The transformation
+      # preserves the structure while only modifying the keys.
+      #
+      # @param [Object] obj The object to transform (Hash, Array, or other)
+      # @yieldparam [String, Symbol] key Each hash key to be transformed
+      # @yieldreturn [String, Symbol] The transformed key
+      # @return [Object] The transformed object with modified keys
+      #
+      # @example Transforming a simple hash
+      #   data = { user_name: "john", user_email: "john@example.com" }
+      #   KeyTransformer.deep_transform_keys(data) { |key| key.to_s.upcase }
+      #   # => { "USER_NAME" => "john", "USER_EMAIL" => "john@example.com" }
+      #
+      # @example Transforming nested structures
+      #   nested = {
+      #     user_info: {
+      #       first_name: "John",
+      #       addresses: [
+      #         { street_name: "Main St", zip_code: "12345" }
+      #       ]
+      #     }
+      #   }
+      #   result = KeyTransformer.deep_transform_keys(nested) { |key|
+      #     KeyTransformer.camelize(key, :lowerCamelCase)
+      #   }
+      #   # => {
+      #   #   userInfo: {
+      #   #     firstName: "John",
+      #   #     addresses: [
+      #   #       { streetName: "Main St", zipCode: "12345" }
+      #   #     ]
+      #   #   }
+      #   # }
+      #
+      # @example Non-hash objects are preserved
+      #   mixed = ["string", 123, { user_name: "john" }]
+      #   KeyTransformer.deep_transform_keys(mixed) { |key| key.to_s.upcase }
+      #   # => ["string", 123, { "USER_NAME" => "john" }]
+      #
       def self.deep_transform_keys(obj, &block)
         case obj
         when Hash

data/lib/securial/helpers/normalizing_helper.rb

@@ -1,14 +1,83 @@
+# @title Securial Normalizing Helpers
+#
+# Data normalization utilities for the Securial framework.
+#
+# This module provides utilities for normalizing user input data to ensure
+# consistency across the application. It handles common normalization tasks
+# like email address formatting and role name standardization to prevent
+# data inconsistencies and improve user experience.
+#
+# @example Normalizing email addresses
+#   email = NormalizingHelper.normalize_email_address("  USER@EXAMPLE.COM  ")
+#   # => "user@example.com"
+#
+# @example Normalizing role names
+#   role = NormalizingHelper.normalize_role_name("  admin user  ")
+#   # => "Admin User"
+#
 module Securial
   module Helpers
+    # Provides data normalization methods for common input sanitization.
+    #
+    # This module contains methods to normalize various types of user input
+    # to ensure data consistency and prevent common formatting issues that
+    # could lead to duplicate records or authentication problems.
+    #
     module NormalizingHelper
       extend self
 
+      # Normalizes an email address for consistent storage and comparison.
+      #
+      # Strips whitespace and converts to lowercase to ensure email addresses
+      # are stored consistently regardless of how users input them. This prevents
+      # duplicate accounts and authentication issues caused by case sensitivity.
+      #
+      # @param [String] email The email address to normalize
+      # @return [String] The normalized email address, or empty string if input is empty
+      #
+      # @example Standard normalization
+      #   normalize_email_address("  USER@EXAMPLE.COM  ")
+      #   # => "user@example.com"
+      #
+      # @example Handling empty input
+      #   normalize_email_address("")
+      #   # => ""
+      #
+      # @example Preserving valid format
+      #   normalize_email_address("user@example.com")
+      #   # => "user@example.com"
+      #
       def normalize_email_address(email)
         return "" if email.empty?
 
         email.strip.downcase
       end
 
+      # Normalizes a role name for consistent display and storage.
+      #
+      # Strips whitespace, converts to lowercase, then applies title case formatting
+      # to ensure role names are displayed consistently across the application.
+      # This helps maintain a professional appearance and prevents formatting issues.
+      #
+      # @param [String] role_name The role name to normalize
+      # @return [String] The normalized role name in title case, or empty string if input is empty
+      #
+      # @example Standard normalization
+      #   normalize_role_name("  admin user  ")
+      #   # => "Admin User"
+      #
+      # @example Handling mixed case input
+      #   normalize_role_name("SUPER_ADMIN")
+      #   # => "Super Admin"
+      #
+      # @example Handling empty input
+      #   normalize_role_name("")
+      #   # => ""
+      #
+      # @example Single word roles
+      #   normalize_role_name("admin")
+      #   # => "Admin"
+      #
       def normalize_role_name(role_name)
         return "" if role_name.empty?
 

data/lib/securial/helpers/regex_helper.rb

@@ -1,18 +1,140 @@
+# @title Securial Regex Helpers
+#
+# Regular expression utilities for data validation in the Securial framework.
+#
+# This module provides commonly used regular expressions and validation methods
+# for user input such as email addresses, usernames, and passwords. It ensures
+# consistent validation rules across the application and helps maintain data
+# integrity and security standards.
+#
+# @example Validating an email address
+#   RegexHelper.valid_email?("user@example.com")
+#   # => true
+#
+# @example Validating a username
+#   RegexHelper.valid_username?("john_doe123")
+#   # => true
+#
+# @example Checking password complexity
+#   password = "MyPass123!"
+#   password.match?(RegexHelper::PASSWORD_REGEX)
+#   # => true
+#
+require "uri"
+
 module Securial
   module Helpers
+    # Regular expression patterns and validation methods for common data types.
+    #
+    # This module centralizes regex patterns used throughout Securial for
+    # validating user input. It provides both the raw regex patterns as
+    # constants and convenience methods for validation.
+    #
     module RegexHelper
+      # RFC-compliant email address validation pattern.
+      #
+      # Uses Ruby's built-in URI::MailTo::EMAIL_REGEXP which follows RFC 3696
+      # specifications for email address validation.
+      #
+      # @return [Regexp] Email validation regular expression
+      #
       EMAIL_REGEX = URI::MailTo::EMAIL_REGEXP
+
+      # Username validation pattern with specific formatting rules.
+      #
+      # Enforces the following username requirements:
+      # - Must start with a letter (not a number)
+      # - Can contain letters, numbers, periods, and underscores
+      # - Cannot have consecutive periods or underscores
+      # - Must end with a letter or number
+      # - Minimum length of 2 characters
+      #
+      # @return [Regexp] Username validation regular expression
+      #
       USERNAME_REGEX = /\A(?![0-9])[a-zA-Z](?:[a-zA-Z0-9]|[._](?![._]))*[a-zA-Z0-9]\z/
+
+      # Password complexity validation pattern.
+      #
+      # Enforces strong password requirements including:
+      # - At least one digit (0-9)
+      # - At least one lowercase letter (a-z)
+      # - At least one uppercase letter (A-Z)
+      # - At least one special character (non-alphanumeric)
+      # - Must start with a letter
+      #
+      # @return [Regexp] Password complexity validation regular expression
+      #
       PASSWORD_REGEX = %r{\A(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[^a-zA-Z0-9])[a-zA-Z].*\z}
 
       extend self
+
+      # Validates if an email address matches the RFC-compliant pattern.
+      #
+      # Uses the EMAIL_REGEX pattern to check if the provided email address
+      # follows proper email formatting standards.
+      #
+      # @param [String] email The email address to validate
+      # @return [Boolean] true if the email is valid, false otherwise
+      #
+      # @example Valid email addresses
+      #   valid_email?("user@example.com")        # => true
+      #   valid_email?("test.email@domain.co.uk") # => true
+      #   valid_email?("user+tag@example.org")    # => true
+      #
+      # @example Invalid email addresses
+      #   valid_email?("invalid.email")           # => false
+      #   valid_email?("@example.com")            # => false
+      #   valid_email?("user@")                   # => false
+      #
       def valid_email?(email)
         email.match?(EMAIL_REGEX)
       end
 
+      # Validates if a username follows the defined formatting rules.
+      #
+      # Uses the USERNAME_REGEX pattern to check if the provided username
+      # meets the application's username requirements.
+      #
+      # @param [String] username The username to validate
+      # @return [Boolean] true if the username is valid, false otherwise
+      #
+      # @example Valid usernames
+      #   valid_username?("john_doe")      # => true
+      #   valid_username?("user123")       # => true
+      #   valid_username?("test.user")     # => true
+      #   valid_username?("a1")            # => true
+      #
+      # @example Invalid usernames
+      #   valid_username?("123user")       # => false (starts with number)
+      #   valid_username?("user__name")    # => false (consecutive underscores)
+      #   valid_username?("user.")         # => false (ends with period)
+      #   valid_username?("a")             # => false (too short)
+      #
       def valid_username?(username)
         username.match?(USERNAME_REGEX)
       end
+
+      # Validates if a password meets complexity requirements.
+      #
+      # Uses the PASSWORD_REGEX pattern to check if the provided password
+      # meets the application's security standards.
+      #
+      # @param [String] password The password to validate
+      # @return [Boolean] true if the password meets complexity requirements, false otherwise
+      #
+      # @example Valid passwords
+      #   valid_password?("MyPass123!")    # => true
+      #   valid_password?("Secure@2024")   # => true
+      #   valid_password?("aB3#defgh")     # => true
+      #
+      # @example Invalid passwords
+      #   valid_password?("password")      # => false (no uppercase, number, or special char)
+      #   valid_password?("PASSWORD123")   # => false (no lowercase or special char)
+      #   valid_password?("123Password!")  # => false (starts with number)
+      #
+      def valid_password?(password)
+        password.match?(PASSWORD_REGEX)
+      end
     end
   end
 end

data/lib/securial/helpers/roles_helper.rb

@@ -1,13 +1,82 @@
+# @title Securial Roles Helper
+#
+# Role and permission utilities for the Securial framework.
+#
+# This module provides helper methods for working with user roles and permissions
+# throughout the application. It handles role name formatting, namespace generation,
+# and other role-related operations to ensure consistency across the system.
+#
+# @example Getting the admin namespace for routing
+#   RolesHelper.protected_namespace
+#   # => "admins" (if admin_role is :admin)
+#
+# @example Getting a formatted admin role name for display
+#   RolesHelper.titleized_admin_role
+#   # => "Super Admin" (if admin_role is :super_admin)
+#
 module Securial
   module Helpers
+    # Helper methods for role management and formatting.
+    #
+    # This module provides utility methods for working with user roles,
+    # including namespace generation for protected routes and role name
+    # formatting for user interfaces. It centralizes role-related logic
+    # to ensure consistent behavior across the application.
+    #
     module RolesHelper
-      # This module provides helper methods related to roles.
-      # It can be extended with additional role-related functionality as needed.
       extend self
+
+      # Generates a namespace string for protected admin routes.
+      #
+      # Converts the configured admin role into a pluralized, underscored
+      # namespace suitable for use in Rails routing and controller organization.
+      # This ensures admin routes are consistently organized under the
+      # appropriate namespace.
+      #
+      # @return [String] The pluralized, underscored admin role namespace
+      #
+      # @example With default admin role
+      #   # When Securial.configuration.admin_role = :admin
+      #   protected_namespace
+      #   # => "admins"
+      #
+      # @example With custom admin role
+      #   # When Securial.configuration.admin_role = :super_admin
+      #   protected_namespace
+      #   # => "super_admins"
+      #
+      # @example With spaced role name
+      #   # When Securial.configuration.admin_role = "Site Administrator"
+      #   protected_namespace
+      #   # => "site_administrators"
+      #
       def protected_namespace
         Securial.configuration.admin_role.to_s.strip.underscore.pluralize
       end
 
+      # Formats the admin role name for user interface display.
+      #
+      # Converts the configured admin role into a human-readable, title-cased
+      # string suitable for display in user interfaces, form labels, and
+      # user-facing messages.
+      #
+      # @return [String] The title-cased admin role name
+      #
+      # @example With default admin role
+      #   # When Securial.configuration.admin_role = :admin
+      #   titleized_admin_role
+      #   # => "Admin"
+      #
+      # @example With underscored role name
+      #   # When Securial.configuration.admin_role = :super_admin
+      #   titleized_admin_role
+      #   # => "Super Admin"
+      #
+      # @example With already formatted role
+      #   # When Securial.configuration.admin_role = "Site Administrator"
+      #   titleized_admin_role
+      #   # => "Site Administrator"
+      #
       def titleized_admin_role
         Securial.configuration.admin_role.to_s.strip.titleize
       end

data/lib/securial/helpers.rb

@@ -1,11 +1,55 @@
+# @title Securial Helper Utilities
+#
+# Centralized collection of helper modules for the Securial framework.
+#
+# This file serves as the entry point for all helper functionality in Securial,
+# loading specialized utility modules that provide common functions used
+# throughout the framework. These helpers handle tasks such as normalization,
+# pattern matching, role management, and data transformation, making common
+# operations consistent across the codebase.
+#
+# @example Normalizing user input
+#   # For normalizing email addresses (converts to lowercase)
+#   email = Securial::Helpers::NormalizingHelper.normalize_email("USER@EXAMPLE.COM")
+#   # => "user@example.com"
+#
+# @example Validating input format
+#   # For validating email format
+#   valid = Securial::Helpers::RegexHelper.valid_email?("user@example.com")
+#   # => true
+#
+#   invalid = Securial::Helpers::RegexHelper.valid_email?("not-an-email")
+#   # => false
+#
+# @example Transforming data structure keys
+#   # For transforming keys in response data (snake_case to camelCase)
+#   data = { user_id: 1, first_name: "John", last_name: "Doe" }
+#   json = Securial::Helpers::KeyTransformer.transform(data, :lower_camel_case)
+#   # => { userId: 1, firstName: "John", lastName: "Doe" }
+#
 require "securial/helpers/normalizing_helper"
 require "securial/helpers/regex_helper"
 require "securial/helpers/roles_helper"
 require "securial/helpers/key_transformer"
 
 module Securial
-  module Helpers
-    # This module acts as a namespace for helper modules.
-    # It requires all helper modules to make them available for consumers.
-  end
+  # Namespace containing utility modules for common operations.
+  #
+  # The Helpers module serves as a container for specialized utility modules
+  # that provide reusable functionality across the Securial framework:
+  #
+  # - {NormalizingHelper} - Methods for normalizing user input (emails, usernames, etc.)
+  # - {RegexHelper} - Regular expressions and validation methods for input validation
+  # - {RolesHelper} - Functions for working with user roles and permissions management
+  # - {KeyTransformer} - Tools for transforming data structure keys between formats (snake_case, camelCase)
+  #
+  # These helpers ensure consistent behavior across the application and reduce
+  # code duplication by centralizing common operations.
+  #
+  # @see Securial::Helpers::NormalizingHelper
+  # @see Securial::Helpers::RegexHelper
+  # @see Securial::Helpers::RolesHelper
+  # @see Securial::Helpers::KeyTransformer
+  #
+  module Helpers; end
 end

data/lib/securial/logger/broadcaster.rb

@@ -1,36 +1,109 @@
+# @title Securial Logger Broadcaster
+#
+# Logger broadcasting utility for the Securial framework.
+#
+# This file defines a broadcaster class that sends logging messages to multiple
+# destination loggers simultaneously. This enables unified logging across different
+# outputs (like console and file) while maintaining appropriate formatting for each.
+#
+# @example Creating a broadcaster with multiple loggers
+#   # Create individual loggers
+#   file_logger = Logger.new('application.log')
+#   stdout_logger = Logger.new(STDOUT)
+#
+#   # Combine them into a broadcaster
+#   broadcaster = Securial::Logger::Broadcaster.new([file_logger, stdout_logger])
+#
+#   # Log messages go to both destinations
+#   broadcaster.info("Processing authentication request")
+#
 module Securial
   module Logger
+    # Broadcasts log messages to multiple logger instances simultaneously.
+    #
+    # This class implements the Logger interface and forwards all logging calls
+    # to a collection of underlying loggers. This allows unified logging to
+    # multiple destinations (e.g., file and stdout) while maintaining specific
+    # formatting for each destination.
+    #
+    # @example Using a broadcaster with two loggers
+    #   file_logger = Logger.new('app.log')
+    #   console_logger = Logger.new(STDOUT)
+    #   broadcaster = Broadcaster.new([file_logger, console_logger])
+    #
+    #   # This logs to both destinations
+    #   broadcaster.info("User logged in")
+    #
     class Broadcaster
+      # Initializes a new broadcaster with the provided loggers.
+      #
+      # @param loggers [Array<Logger>] Collection of logger instances
+      # @return [Broadcaster] New broadcaster instance
       def initialize(loggers)
         @loggers = loggers
       end
 
+      # Dynamically define logging methods for each severity level
+      # (debug, info, warn, error, fatal, unknown)
       ::Logger::Severity.constants.each do |severity|
         define_method(severity.downcase) do |*args, &block|
           @loggers.each { |logger| logger.public_send(severity.downcase, *args, &block) }
         end
       end
 
+      # Writes a message to each underlying logger.
+      #
+      # @param msg [String] Message to be written
+      # @return [Array] Results from each logger's << method
       def <<(msg)
         @loggers.each { |logger| logger << msg }
       end
 
+      # Closes all underlying loggers.
+      #
+      # @return [void]
       def close
         @loggers.each(&:close)
       end
 
+      # No-op method to satisfy the Logger interface.
+      #
+      # Since each underlying logger has its own formatter, setting a
+      # formatter on the broadcaster is not supported.
+      #
+      # @param _formatter [Object] Ignored formatter object
+      # @return [void]
       def formatter=(_formatter)
-        # Do nothing
+        # Do nothing - each logger maintains its own formatter
       end
 
+      # Returns nil to satisfy the Logger interface.
+      #
+      # Since each underlying logger has its own formatter, there is
+      # no single formatter for the broadcaster.
+      #
+      # @return [nil] Always returns nil
       def formatter
         nil
       end
 
+      # Returns the collection of managed loggers.
+      #
+      # @return [Array<Logger>] All loggers managed by this broadcaster
+      #
       def loggers
         @loggers
       end
 
+      # Executes a block with the specified tags added to the log.
+      #
+      # Supports ActiveSupport::TaggedLogging by forwarding tagged blocks
+      # to all underlying loggers that support tagging.
+      #
+      # @param tags [Array<String>] Tags to apply to log messages
+      # @yield Block to be executed with the tags applied
+      # @return [Object] Result of the block
+      #
       def tagged(*tags, &block)
         # If all loggers support tagged, nest the calls, otherwise just yield.
         taggable_loggers = @loggers.select { |logger| logger.respond_to?(:tagged) }
@@ -44,10 +117,25 @@ module Securial
         end
       end
 
+      # Checks if the broadcaster responds to the given method.
+      #
+      # @param method [Symbol] Method name to check
+      # @param include_private [Boolean] Whether to include private methods
+      # @return [Boolean] True if any of the underlying loggers respond to the method
       def respond_to_missing?(method, include_private = false)
         @loggers.any? { |logger| logger.respond_to?(method, include_private) } || super
       end
 
+      # Delegates missing methods to all underlying loggers.
+      #
+      # If all loggers respond to the method, it will be called on each logger.
+      # Otherwise, raises a NoMethodError.
+      #
+      # @param method [Symbol] Method name to call
+      # @param args [Array] Arguments to pass to the method
+      # @param block [Proc] Block to pass to the method
+      # @return [Array] Results from each logger's method call
+      # @raise [NoMethodError] If any logger doesn't respond to the method
       def method_missing(method, *args, &block)
         if @loggers.all? { |logger| logger.respond_to?(method) }
           @loggers.map { |logger| logger.send(method, *args, &block) }