securial 1.0.1 → 1.0.2

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) }

data/lib/securial/logger/builder.rb

@@ -1,3 +1,19 @@
+# @title Securial Logger Builder
+#
+# Logger construction utilities for the Securial framework.
+#
+# This file defines a builder class that constructs and configures loggers for the Securial
+# framework based on application configuration. It supports multiple logging destinations
+# (stdout and file) with appropriate formatters for each, and combines them using a
+# broadcaster pattern for unified logging.
+#
+# @example Building a logger with defaults from configuration
+#   # Securial.configuration has been set up elsewhere
+#   logger = Securial::Logger::Builder.build
+#
+#   # Log messages go to both configured destinations
+#   logger.info("User authentication successful")
+#
 require "logger"
 require "active_support/logger"
 require "active_support/tagged_logging"
@@ -7,7 +23,22 @@ require "securial/logger/formatter"
 
 module Securial
   module Logger
+    # Builder for constructing Securial's logging system.
+    #
+    # This class provides factory methods to create properly configured logger instances
+    # based on the application's configuration settings. It supports multiple logging
+    # destinations and handles the setup of formatters, log levels, and tagging.
+    #
     class Builder
+      # Builds a complete logger system based on configuration settings.
+      #
+      # Creates file and/or stdout loggers as specified in configuration and
+      # combines them using a Broadcaster to provide unified logging to multiple
+      # destinations with appropriate formatting for each.
+      #
+      # @return [Securial::Logger::Broadcaster] A broadcaster containing all configured loggers
+      # @see Securial::Logger::Broadcaster
+      #
       def self.build
         loggers = []
         progname = "Securial"
@@ -23,6 +54,17 @@ module Securial
         Broadcaster.new(loggers)
       end
 
+      # Creates and configures a file logger.
+      #
+      # Sets up a logger that writes to a Rails environment-specific log file
+      # with plain text formatting and adds it to the provided loggers array.
+      #
+      # @param progname [String] The program name to include in log entries
+      # @param level [Integer, Symbol] The log level (e.g., :info, :debug)
+      # @param loggers [Array<Logger>] Array to which the new logger will be added
+      # @return [ActiveSupport::TaggedLogging] The configured file logger
+      # @see Securial::Logger::Formatter::PlainFormatter
+      #
       def self.create_file_logger(progname, level, loggers)
         file_logger = ::Logger.new(Rails.root.join("log", "securial-#{Rails.env}.log"))
         file_logger.level = level
@@ -32,12 +74,23 @@ module Securial
         loggers << tagged_file_logger
       end
 
+      # Creates and configures a stdout logger.
+      #
+      # Sets up a logger that writes to standard output with colorful formatting
+      # and adds it to the provided loggers array.
+      #
+      # @param progname [String] The program name to include in log entries
+      # @param level [Integer, Symbol] The log level (e.g., :info, :debug)
+      # @param loggers [Array<Logger>] Array to which the new logger will be added
+      # @return [ActiveSupport::TaggedLogging] The configured stdout logger
+      # @see Securial::Logger::Formatter::ColorfulFormatter
+      #
       def self.create_stdout_logger(progname, level, loggers)
         stdout_logger = ::Logger.new($stdout)
         stdout_logger.level = level
         stdout_logger.progname = progname
         stdout_logger.formatter = Formatter::ColorfulFormatter.new
-        tagged_stdout_logger =  ActiveSupport::TaggedLogging.new(stdout_logger)
+        tagged_stdout_logger = ActiveSupport::TaggedLogging.new(stdout_logger)
         loggers << tagged_stdout_logger
       end
     end

data/lib/securial/logger/formatter.rb

@@ -1,6 +1,33 @@
+# @title Securial Logger Formatters
+#
+# Log formatting utilities for the Securial framework's logging system.
+#
+# This file defines formatter classes that determine how log messages are displayed,
+# providing both colorful terminal-friendly output and plain text output options.
+# These formatters are used by the Securial::Logger system to ensure consistent
+# and readable log formats across different environments.
+#
+# @example Using a formatter with a standard Ruby logger
+#   require 'logger'
+#   logger = Logger.new(STDOUT)
+#   logger.formatter = Securial::Logger::Formatter::ColorfulFormatter.new
+#
+#   logger.info("Application started")
+#   # Output: [2023-11-15 14:30:22] INFO  -- Application started (in green color)
+#
 module Securial
   module Logger
+    # Formatting utilities for Securial's logging system.
+    #
+    # This module contains formatter classes and constants that determine
+    # how log messages are presented. It provides both colored output for
+    # terminal environments and plain text output for file logging.
+    #
     module Formatter
+      # Terminal color codes for different log severity levels.
+      #
+      # @return [Hash{String => String}] Mapping of severity names to ANSI color codes
+      #
       COLORS = {
         "DEBUG" => "\e[36m",   # cyan
         "INFO" => "\e[32m",    # green
@@ -9,10 +36,38 @@ module Securial
         "FATAL" => "\e[35m",   # magenta
         "UNKNOWN" => "\e[37m", # white
       }.freeze
+
+      # ANSI code to reset terminal colors.
+      #
+      # @return [String] Terminal color reset sequence
+      #
       CLEAR = "\e[0m"
+
+      # Width used for severity level padding in log output.
+      #
+      # @return [Integer] Number of characters to use for severity field
+      #
       SEVERITY_WIDTH = 5
 
+      # Formatter that adds color to log output for terminal display.
+      #
+      # This formatter colorizes log messages based on their severity level,
+      # making them easier to distinguish in terminal output. It follows the
+      # standard Ruby Logger formatter interface.
+      #
+      # @example
+      #   logger = Logger.new(STDOUT)
+      #   logger.formatter = Securial::Logger::Formatter::ColorfulFormatter.new
+      #
       class ColorfulFormatter
+        # Formats a log message with color based on severity.
+        #
+        # @param severity [String] Log severity level (DEBUG, INFO, etc.)
+        # @param timestamp [Time] Time when the log event occurred
+        # @param progname [String] Program name or context for the log message
+        # @param msg [String] The log message itself
+        # @return [String] Formatted log message with appropriate ANSI color codes
+        #
         def call(severity, timestamp, progname, msg)
           color = COLORS[severity] || CLEAR
           padded_severity = severity.ljust(SEVERITY_WIDTH)
@@ -22,7 +77,25 @@ module Securial
         end
       end
 
+      # Formatter that produces plain text log output without colors.
+      #
+      # This formatter is suitable for file logging or environments where
+      # terminal colors are not supported. It follows the standard Ruby
+      # Logger formatter interface.
+      #
+      # @example
+      #   logger = Logger.new('application.log')
+      #   logger.formatter = Securial::Logger::Formatter::PlainFormatter.new
+      #
       class PlainFormatter
+        # Formats a log message in plain text without color codes.
+        #
+        # @param severity [String] Log severity level (DEBUG, INFO, etc.)
+        # @param timestamp [Time] Time when the log event occurred
+        # @param progname [String] Program name or context for the log message
+        # @param msg [String] The log message itself
+        # @return [String] Formatted log message as plain text
+        #
         def call(severity, timestamp, progname, msg)
           padded_severity = severity.ljust(SEVERITY_WIDTH)
           formatted = "[#{timestamp.strftime("%Y-%m-%d %H:%M:%S")}] #{padded_severity} -- #{msg}\n"

data/lib/securial/logger.rb

@@ -1,13 +1,54 @@
+# @title Securial Logger Configuration
+#
+# Defines the logging interface for the Securial framework.
+#
+# This file establishes the logging system for Securial, providing methods
+# to access and configure the application's logger instance. By default,
+# it initializes a logger using the Securial::Logger::Builder class, which
+# configures appropriate log levels and formatters based on the current environment.
+#
+# @example Basic logging usage
+#   # Log messages at different levels
+#   Securial.logger.debug("Detailed debugging information")
+#   Securial.logger.info("General information about system operation")
+#   Securial.logger.warn("Warning about potential issue")
+#   Securial.logger.error("Error condition")
+#
+# @example Setting a custom logger
+#   # Configure a custom logger
+#   custom_logger = Logger.new(STDOUT)
+#   custom_logger.level = :info
+#   Securial.logger = custom_logger
+#
 require_relative "logger/builder"
 
 module Securial
   extend self
   attr_accessor :logger
 
+  # Returns the logger instance used by Securial.
+  #
+  # If no logger has been set, initializes a new logger instance using
+  # the Securial::Logger::Builder class, which configures the logger
+  # based on the current environment settings.
+  #
+  # @return [Securial::Logger::Builder] the configured logger instance
+  # @see Securial::Logger::Builder
   def logger
-    @logger ||= Logger::Builder.build
+    @logger ||= Securial::Logger::Builder.build
   end
 
+  # Sets the logger instance for Securial.
+  #
+  # This allows applications to provide their own custom logger
+  # implementation that may have specialized formatting or output
+  # destinations.
+  #
+  # @param logger [Logger] a Logger-compatible object that responds to standard
+  #   logging methods (debug, info, warn, error, fatal)
+  # @return [Logger] the newly set logger instance
+  # @example
+  #   Securial.logger = Rails.logger
   def logger=(logger)
     @logger = logger
   end

data/lib/securial/middleware.rb

@@ -1,16 +1,47 @@
+# @title Securial Middleware Components
+#
+# Rack middleware components for the Securial framework.
+#
+# This file serves as the entry point for middleware-related functionality in Securial,
+# loading specialized middleware classes that provide features like request/response
+# processing, logging enhancements, and security header management.
+#
 require "securial/middleware/request_tag_logger"
 require "securial/middleware/transform_request_keys"
 require "securial/middleware/transform_response_keys"
 require "securial/middleware/response_headers"
 
 module Securial
-  module Middleware
-    # This module serves as a namespace for all middleware components in the Securial gem.
-    # It currently includes the RequestTagLogger middleware, which tags logs with request IDs.
-    #
-    # Additional middleware can be added here as the gem evolves.
-    #
-    # Example usage:
-    #   use Securial::Middleware::RequestTagLogger
-  end
+  # Namespace for Rack middleware components in the Securial framework.
+  #
+  # This module contains several middleware components that enhance Rails applications:
+  #
+  # - {RequestTagLogger} - Tags logs with request IDs for better traceability
+  # - {TransformRequestKeys} - Transforms incoming request parameter keys to a consistent format
+  # - {TransformResponseKeys} - Transforms outgoing response JSON keys to match client conventions
+  # - {ResponseHeaders} - Adds security headers to responses based on configuration
+  #
+  # @example Using middleware in a Rails application (config/application.rb)
+  #   module YourApp
+  #     class Application < Rails::Application
+  #       # Add request logging with unique IDs
+  #       config.middleware.use Securial::Middleware::RequestTagLogger
+  #
+  #       # Transform request keys from camelCase to snake_case
+  #       config.middleware.use Securial::Middleware::TransformRequestKeys
+  #
+  #       # Transform response keys from snake_case to camelCase
+  #       config.middleware.use Securial::Middleware::TransformResponseKeys
+  #
+  #       # Add security headers to all responses
+  #       config.middleware.use Securial::Middleware::ResponseHeaders
+  #     end
+  #   end
+  #
+  # @see Securial::Middleware::RequestTagLogger
+  # @see Securial::Middleware::TransformRequestKeys
+  # @see Securial::Middleware::TransformResponseKeys
+  # @see Securial::Middleware::ResponseHeaders
+  #
+  module Middleware; end
 end

data/lib/securial/security/request_rate_limiter.rb

@@ -1,11 +1,57 @@
+# @title Securial Request Rate Limiter
+#
+# Rate limiting middleware for protecting authentication endpoints in the Securial framework.
+#
+# This file implements rate limiting for sensitive endpoints like login and password reset,
+# protecting them from brute force attacks, credential stuffing, and denial of service attempts.
+# It uses the Rack::Attack middleware to track and limit request rates based on IP address
+# and provided credentials.
+#
+# @example Basic configuration in a Rails initializer
+#   # In config/initializers/securial.rb
+#   Securial.configure do |config|
+#     config.rate_limit_requests_per_minute = 5
+#     config.rate_limit_response_status = 429
+#     config.rate_limit_response_message = "Too many requests. Please try again later."
+#   end
+#
+#   # Apply rate limiting
+#   Securial::Security::RequestRateLimiter.apply!
+#
 require "rack/attack"
 require "securial/config"
 
 module Securial
   module Security
+    # Protects authentication endpoints with configurable rate limiting.
+    #
+    # This module provides Rack::Attack-based rate limiting for sensitive Securial
+    # endpoints, preventing brute force attacks and abuse. It limits requests based
+    # on both IP address and credential values (like email address), providing
+    # multi-dimensional protection against different attack vectors.
+    #
+    # Protected endpoints include:
+    # - Login attempts (/sessions/login)
+    # - Password reset requests (/password/forgot)
+    #
     module RequestRateLimiter
       extend self
 
+      # Applies rate limiting rules to the Rack::Attack middleware.
+      #
+      # This method configures Rack::Attack with throttling rules for sensitive endpoints
+      # and sets up a custom JSON response format for throttled requests. It should be
+      # called during application initialization, typically in a Rails initializer.
+      #
+      # Rate limits are defined using settings from the Securial configuration:
+      # - rate_limit_requests_per_minute: Maximum requests allowed per minute
+      # - rate_limit_response_status: HTTP status code to return (typically 429)
+      # - rate_limit_response_message: Message to include in throttled responses
+      #
+      # @return [void]
+      # @see Securial::Config::Configuration
+      # @see Rack::Attack
+      #
       def apply! # rubocop:disable Metrics/MethodLength
         resp_status = Securial.configuration.rate_limit_response_status
         resp_message = Securial.configuration.rate_limit_response_message
@@ -36,7 +82,7 @@ module Securial
               "Content-Type" => "application/json",
               "Retry-After" => retry_after.to_s,
             },
-            [{ error: resp_message }.to_json],
+            [{ errors: [resp_message] }.to_json],
           ]
         end
       end

data/lib/securial/security.rb

@@ -1,8 +1,39 @@
+# @title Securial Security Components
+#
+# Security components and protections for the Securial framework.
+#
+# This file serves as the entry point for security-related functionality in Securial,
+# loading specialized security modules that provide protection mechanisms including
+# rate limiting, CSRF protection, and other security measures to safeguard
+# Securial-powered applications.
+#
+# @example Using the rate limiter
+#   # Set up a rate limiter for login attempts
+#   limiter = Securial::Security::RequestRateLimiter.new(
+#     max_requests: 5,
+#     period: 1.minute,
+#     block_duration: 15.minutes
+#   )
+#
+#   # Check if a request is allowed
+#   if limiter.allowed?(request.ip)
+#     # Process login attempt
+#   else
+#     # Return rate limit exceeded response
+#   end
+#
 require "securial/security/request_rate_limiter"
 
- module Securial
-  module Security
-    # This module serves as a namespace for security-related functionality.
-    # It can be extended with additional security features in the future.
-  end
- end
+module Securial
+  # Namespace for security-related functionality in the Securial framework.
+  #
+  # The Security module contains components that implement various security
+  # measures to protect applications from common attacks and threats:
+  #
+  # - {RequestRateLimiter} - Protection against brute force and DoS attacks
+  # - Additional security components may be added in future versions
+  #
+  # @see Securial::Security::RequestRateLimiter
+  #
+  module Security; end
+end

data/lib/securial/version.rb

@@ -1,3 +1,10 @@
 module Securial
-  VERSION = "1.0.1".freeze
+  # Current version of the Securial gem.
+  #
+  # This constant is used by the gem specification to determine the version of the gem
+  # when it is built and published to RubyGems. It follows Semantic Versioning 2.0.0.
+  #
+  # @see https://semver.org/ Semantic Versioning 2.0.0
+  # @return [String] the current version in the format "major.minor.patch"
+  VERSION = "1.0.2".freeze
 end

data/lib/securial.rb

@@ -1,11 +1,47 @@
+# Main entry point for the Securial gem.
+#
+# This file serves as the primary entry point for the Securial gem,
+# requiring necessary dependencies, setting up the module structure,
+# and establishing method delegation.
+#
+# The Securial gem is a mountable Rails engine that provides authentication
+# and authorization capabilities for Rails applications, supporting JWT,
+# API tokens, and session-based authentication.
+#
+# @example Basic usage in a Rails application
+#   # In Gemfile
+#   gem 'securial'
+#
+#   # In routes.rb
+#   Rails.application.routes.draw do
+#     mount Securial::Engine => '/securial'
+#   end
+#
+# @see Securial::Engine
+# @see Securial::VERSION
+#
 require "securial/version"
 require "securial/engine"
 
 require "jbuilder"
 
+# Main namespace for the Securial authentication and authorization framework.
+#
+# This module provides access to core functionality of the Securial gem
+# by exposing key helper methods and serving as the root namespace for
+# all Securial components.
+#
 module Securial
   extend self
 
+  # @!method protected_namespace
+  #   Returns the namespace used for protected resources in the application.
+  #   @return [String] the protected namespace designation
+
+  # @!method titleized_admin_role
+  #   Returns the admin role name with proper title-case formatting.
+  #   @return [String] the admin role title
+
   delegate :protected_namespace, to: Securial::Helpers::RolesHelper
   delegate :titleized_admin_role, to: Securial::Helpers::RolesHelper
 end