securial 1.0.2 → 1.0.3

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/middleware/request_tag_logger.rb

@@ -1,11 +1,62 @@
+# @title Securial Request Tag Logger Middleware
+#
+# Rack middleware for adding request context to log messages.
+#
+# This middleware automatically tags all log messages within a request with
+# contextual information like request ID, IP address, and user agent. This
+# enables better tracking and debugging of requests across the application
+# by providing consistent context in all log entries.
+#
+# @example Adding middleware to Rails application
+#   # config/application.rb
+#   config.middleware.use Securial::Middleware::RequestTagLogger
+#
+# @example Log output with request tags
+#   # Without middleware:
+#   [2024-06-27 10:30:15] INFO  -- User authentication successful
+#
+#   # With middleware:
+#   [2024-06-27 10:30:15] INFO  -- [abc123-def456] [IP:192.168.1.100] [UA:Mozilla/5.0...] User authentication successful
+#
 module Securial
   module Middleware
+    # Rack middleware that adds request context tags to log messages.
+    #
+    # This middleware intercepts requests and wraps the application call
+    # with tagged logging, ensuring all log messages generated during
+    # request processing include relevant request metadata for better
+    # traceability and debugging.
+    #
     class RequestTagLogger
+      # Initializes the middleware with the Rack application and logger.
+      #
+      # @param [#call] app The Rack application to wrap
+      # @param [Logger] logger The logger instance to use for tagging (defaults to Securial.logger)
+      #
+      # @example
+      #   middleware = RequestTagLogger.new(app, Rails.logger)
+      #
       def initialize(app, logger = Securial.logger)
         @app = app
         @logger = logger
       end
 
+      # Processes the request with tagged logging context.
+      #
+      # Extracts request metadata from the Rack environment and applies
+      # them as tags to all log messages generated during the request
+      # processing. Tags are automatically removed after the request completes.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [Array] The Rack response array [status, headers, body]
+      #
+      # @example Request processing with tags
+      #   # All log messages during this request will include:
+      #   # - Request ID (if available)
+      #   # - IP address (if available)
+      #   # - User agent (if available)
+      #   response = middleware.call(env)
+      #
       def call(env)
         request_id = request_id_from_env(env)
         ip_address = ip_from_env(env)
@@ -23,14 +74,43 @@ module Securial
 
       private
 
+      # Extracts the request ID from the Rack environment.
+      #
+      # Looks for request ID in ActionDispatch's request_id or the
+      # X-Request-ID header, providing request traceability across
+      # multiple services and log aggregation systems.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [String, nil] The request ID if found, nil otherwise
+      # @api private
+      #
       def request_id_from_env(env)
         env["action_dispatch.request_id"] || env["HTTP_X_REQUEST_ID"]
       end
 
+      # Extracts the client IP address from the Rack environment.
+      #
+      # Prioritizes ActionDispatch's processed remote IP (which handles
+      # proxy headers) over the raw REMOTE_ADDR to ensure accurate
+      # client identification behind load balancers and proxies.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [String, nil] The client IP address if found, nil otherwise
+      # @api private
+      #
       def ip_from_env(env)
         env["action_dispatch.remote_ip"]&.to_s || env["REMOTE_ADDR"]
       end
 
+      # Extracts the user agent string from the Rack environment.
+      #
+      # Retrieves the HTTP User-Agent header to provide context about
+      # the client application or browser making the request.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [String, nil] The user agent string if found, nil otherwise
+      # @api private
+      #
       def user_agent_from_env(env)
         env["HTTP_USER_AGENT"]
       end

data/lib/securial/middleware/response_headers.rb

@@ -1,17 +1,65 @@
+# @title Securial Response Headers Middleware
+#
+# Rack middleware for adding Securial-specific headers to HTTP responses.
+#
+# This middleware automatically adds identification headers to all HTTP responses
+# to indicate that the application is using Securial for authentication and to
+# provide developer attribution. These headers can be useful for debugging,
+# monitoring, and identifying Securial-powered applications.
+#
+# @example Adding middleware to Rails application
+#   # config/application.rb
+#   config.middleware.use Securial::Middleware::ResponseHeaders
+#
+# @example Response headers added by middleware
+#   # HTTP Response Headers:
+#   X-Securial-Mounted: true
+#   X-Securial-Developer: Aly Badawy - https://alybadawy.com | @alybadawy
+#
 module Securial
   module Middleware
-    # This middleware removes sensitive headers from the request environment.
-    # It is designed to enhance security by ensuring that sensitive information
-    # is not inadvertently logged or processed.
+    # Rack middleware that adds Securial identification headers to responses.
+    #
+    # This middleware enhances security transparency by clearly identifying
+    # when Securial is mounted in an application and provides developer
+    # attribution information in response headers.
+    #
     class ResponseHeaders
+      # Initializes the middleware with the Rack application.
+      #
+      # @param [#call] app The Rack application to wrap
+      #
+      # @example
+      #   middleware = ResponseHeaders.new(app)
+      #
       def initialize(app)
         @app = app
       end
 
+      # Processes the request and adds Securial headers to the response.
+      #
+      # Calls the wrapped application and then adds identification headers
+      # to the response before returning it to the client. The headers
+      # provide clear indication of Securial usage and developer attribution.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [Array] The Rack response array [status, headers, body] with added headers
+      #
+      # @example Headers added to response
+      #   # Original response headers remain unchanged
+      #   # Additional headers added:
+      #   # X-Securial-Mounted: "true"
+      #   # X-Securial-Developer: "Aly Badawy - https://alybadawy.com | @alybadawy"
+      #
       def call(env)
         status, headers, response = @app.call(env)
+
+        # Indicate that Securial is mounted and active
         headers["X-Securial-Mounted"] = "true"
+
+        # Provide developer attribution
         headers["X-Securial-Developer"] = "Aly Badawy - https://alybadawy.com | @alybadawy"
+
         [status, headers, response]
       end
     end