securial 1.0.0 → 1.0.2

data/lib/securial/config.rb

@@ -1,28 +1,74 @@
+# @title Securial Configuration System
+#
+# Configuration management for the Securial framework.
+#
+# This file defines the configuration system for Securial, providing mechanisms
+# to set, retrieve, and validate configuration options. It uses a conventional
+# Ruby configuration block pattern to allow applications to customize Securial's
+# behavior through an easy-to-use interface.
+#
+# @example Basic configuration
+#   # In config/initializers/securial.rb
+#   Securial.configure do |config|
+#     config.jwt_secret = ENV["JWT_SECRET"]
+#     config.token_expiry = 2.hours
+#     config.refresh_token_expiry = 7.days
+#     config.session_timeout = 1.hour
+#   end
+#
+# @example Accessing configuration values
+#   # Get the configured token expiry
+#   expiry = Securial.configuration.token_expiry
+#
 require "securial/config/configuration"
 require "securial/config/signature"
 require "securial/config/validation"
 
-
 module Securial
-  class << self
-    attr_accessor :configuration
-
-    def configuration
-      @configuration ||= Config::Configuration.new
-    end
+  extend self
 
-    def configuration=(config)
-      if config.is_a?(Config::Configuration)
-        @configuration = config
-        Securial::Config::Validation.validate_all!(configuration)
-      else
-        raise ArgumentError, "Expected an instance of Securial::Config::Configuration"
-      end
-    end
+  # Gets the current configuration instance.
+  #
+  # Returns the existing configuration or creates a new default configuration
+  # if one hasn't been set yet.
+  #
+  # @return [Securial::Config::Configuration] the current configuration instance
+  def configuration
+    @configuration ||= Config::Configuration.new
+  end
 
-    def configure
-      yield(configuration) if block_given?
+  # Sets the configuration instance.
+  #
+  # Validates the provided configuration to ensure all required settings
+  # are present and have valid values.
+  #
+  # @param config [Securial::Config::Configuration] the configuration instance to use
+  # @raise [ArgumentError] if the provided object is not a Configuration instance
+  # @raise [Securial::Error::Config::ValidationError] if the configuration is invalid
+  # @return [Securial::Config::Configuration] the newly set configuration
+  #
+  def configuration=(config)
+    if config.is_a?(Config::Configuration)
+      @configuration = config
       Securial::Config::Validation.validate_all!(configuration)
+    else
+      raise ArgumentError, "Expected an instance of Securial::Config::Configuration"
     end
   end
+
+  # Configures the Securial framework using a block.
+  #
+  # This method provides the conventional Ruby configuration block pattern,
+  # yielding the current configuration instance to the provided block for
+  # modification. After the block executes, the configuration is validated.
+  #
+  # @yield [config] Yields the configuration instance to the block
+  # @yieldparam config [Securial::Config::Configuration] the configuration instance
+  # @raise [Securial::Error::Config::ValidationError] if the configuration is invalid
+  # @return [Securial::Config::Configuration] the updated configuration
+  def configure
+    yield(configuration) if block_given?
+    Securial::Config::Validation.validate_all!(configuration)
+    configuration
+  end
 end

data/lib/securial/engine.rb

@@ -1,3 +1,25 @@
+# @title Securial Rails Engine
+#
+# Rails engine configuration for the Securial framework.
+#
+# This file defines the core Rails engine that powers Securial, setting up
+# namespace isolation, generator defaults, and loading all required components.
+# The engine configuration establishes how Securial integrates with host Rails
+# applications and defines the conventions used throughout the codebase.
+#
+# @example Mounting the engine in a Rails application
+#   # In config/routes.rb
+#   Rails.application.routes.draw do
+#     mount Securial::Engine => '/securial'
+#   end
+#
+# @example Accessing engine routes in views or controllers
+#   # Generate path to Securial login
+#   securial.login_path
+#
+#   # Generate URL to Securial user profile
+#   securial.user_url(@user)
+#
 require "securial/auth"
 require "securial/config"
 require "securial/error"
@@ -7,11 +29,29 @@ require "securial/middleware"
 require "securial/security"
 
 module Securial
+  # Rails engine implementation for the Securial framework.
+  #
+  # This class defines the core engine that powers Securial's integration with
+  # Rails applications. It isolates all Securial components within their own
+  # namespace to prevent conflicts with host application code and configures
+  # generator defaults to ensure consistent code generation.
+  #
+  # The engine handles:
+  # - Namespace isolation to prevent conflicts
+  # - Configuration of generators for consistent code generation
+  # - Setting up Securial's API-only mode for JSON responses
+  # - Loading initializers for various framework components
+  #
+  # @see https://guides.rubyonrails.org/engines.html Rails Engines Guide
+  #
   class Engine < ::Rails::Engine
+    # Isolates the Securial namespace to prevent conflicts with host applications
     isolate_namespace Securial
 
+    # Configures the engine for API-only mode by default
     config.generators.api_only = true
 
+    # Sets up standard generator configurations for consistent code generation
     config.generators do |g|
       g.orm :active_record, primary_key_type: :string
       g.test_framework :rspec,
@@ -28,4 +68,5 @@ module Securial
   end
 end
 
+# Load engine initializers that configure various aspects of the framework
 require_relative "engine_initializers"

data/lib/securial/error/auth.rb

@@ -1,18 +1,70 @@
+# @title Securial Authentication Errors
+#
+# Authentication-related errors for the Securial framework.
+#
+# This file defines error classes for authentication-related issues in the
+# Securial framework, such as token encoding/decoding failures, expired tokens,
+# and revoked sessions. These errors help identify and troubleshoot problems
+# with the authentication system during runtime.
+#
+# @example Handling authentication errors
+#   begin
+#     decoded_token = Securial::Auth::AuthEncoder.decode(token)
+#   rescue Securial::Error::Auth::TokenDecodeError => e
+#     # Handle invalid token format
+#     logger.warn("Invalid token format: #{e.message}")
+#   rescue Securial::Error::Auth::TokenExpiredError => e
+#     # Handle expired token
+#     render json: { error: "Your session has expired. Please log in again." }, status: :unauthorized
+#   rescue Securial::Error::Auth::TokenRevokedError => e
+#     # Handle revoked token
+#     render json: { error: "Your session has been revoked." }, status: :unauthorized
+#   end
+#
 module Securial
   module Error
+    # Namespace for authentication-related errors in the Securial framework.
+    #
+    # These errors are raised during authentication operations such as
+    # token encoding/decoding, session validation, and access control checks.
+    #
     module Auth
+      # Error raised when a JWT token cannot be encoded properly.
+      #
+      # This may occur due to invalid payload data, missing required claims,
+      # or issues with the signing key.
+      #
+      # @see Securial::Auth::AuthEncoder#encode
+      #
       class TokenEncodeError < BaseError
         default_message "Error while encoding session token"
       end
 
+      # Error raised when a JWT token cannot be decoded or validated.
+      #
+      # This may occur due to malformed tokens, invalid signatures,
+      # or tokens that don't match the expected format.
+      #
+      # @see Securial::Auth::AuthEncoder#decode
+      #
       class TokenDecodeError < BaseError
         default_message "Error while decoding session token"
       end
 
+      # Error raised when attempting to use a token from a revoked session.
+      #
+      # This occurs when a token references a session that has been
+      # explicitly revoked, such as after a user logout or account suspension.
+      #
       class TokenRevokedError < BaseError
         default_message "Session token is revoked"
       end
 
+      # Error raised when attempting to use an expired token.
+      #
+      # This occurs when a token's expiration time (exp claim) has passed,
+      # indicating that the token is no longer valid for authentication.
+      #
       class TokenExpiredError < BaseError
         default_message "Session token is expired"
       end

data/lib/securial/error/base_securial_error.rb

@@ -1,15 +1,68 @@
+# @title Securial Base Error
+#
+# Base error class for the Securial framework.
+#
+# This file defines the base error class that all other specialized Securial
+# errors inherit from. It provides functionality for default error messages
+# and customized backtrace handling.
+#
 module Securial
   module Error
+    # Base error class for all Securial-specific exceptions.
+    #
+    # This class serves as the foundation for Securial's error hierarchy, providing
+    # common functionality like default messages and backtrace customization.
+    # All specialized error types in Securial should inherit from this class.
+    #
+    # @example Defining a custom error class
+    #   module Securial
+    #     module Error
+    #       class AuthError < BaseError
+    #         default_message "Authentication failed"
+    #       end
+    #     end
+    #   end
+    #
+    # @example Raising a custom error
+    #   raise Securial::Error::AuthError
+    #   # => Authentication failed (Securial::Error::AuthError)
+    #
+    #   raise Securial::Error::AuthError, "Invalid token provided"
+    #   # => Invalid token provided (Securial::Error::AuthError)
+    #
     class BaseError < StandardError
+      class_attribute :_default_message, instance_writer: false
+
+      # Sets or gets the default message for this error class.
+      #
+      # This class method allows error classes to define a standard message
+      # that will be used when no explicit message is provided at instantiation.
+      #
+      # @param message [String, nil] The default message to set for this error class
+      # @return [String, nil] The current default message for this error class
+      #
       def self.default_message(message = nil)
-        @default_message = message if message
-        @default_message
+        self._default_message = message if message
+        self._default_message
       end
 
+      # Initializes a new error instance with the provided message or default.
+      #
+      # @param message [String, nil] The error message or nil to use default
+      # @return [BaseError] New error instance
+      #
       def initialize(message = nil)
-        super(message || self.class.default_message || "An error occurred in Securial")
+        super(message || self.class._default_message || "An error occurred in Securial")
       end
 
+      # Returns an empty backtrace.
+      #
+      # This method overrides the standard backtrace behavior to return an empty array,
+      # which helps keep error responses clean without showing internal implementation
+      # details in production environments.
+      #
+      # @return [Array] An empty array
+      #
       def backtrace; []; end
     end
   end

data/lib/securial/error/config.rb

@@ -1,6 +1,39 @@
+# @title Securial Configuration Errors
+#
+# Configuration-related errors for the Securial framework.
+#
+# This file defines error classes for configuration-related issues in the
+# Securial framework, such as missing or invalid configuration options.
+# These errors help identify and troubleshoot problems with application setup.
+#
 module Securial
   module Error
+    # Namespace for configuration-related errors in the Securial framework.
+    #
+    # These errors are raised when the Securial configuration is invalid,
+    # missing required values, or contains values that don't meet validation
+    # requirements.
+    #
+    # @example Handling configuration errors
+    #   begin
+    #     Securial.configure do |config|
+    #       # Configure Securial settings
+    #     end
+    #   rescue Securial::Error::Config::InvalidConfigurationError => e
+    #     Rails.logger.error("Securial configuration error: #{e.message}")
+    #     # Handle configuration error
+    #   end
+    #
     module Config
+      # Error raised when Securial configuration is invalid.
+      #
+      # This error is typically raised during application initialization when
+      # the provided configuration doesn't meet requirements, such as missing
+      # required settings or having values that fail validation.
+      #
+      # @example Raising a configuration error
+      #   raise InvalidConfigurationError, "JWT secret is missing"
+      #
       class InvalidConfigurationError < Securial::Error::BaseError
         default_message "Invalid configuration for Securial"
       end

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,7 +1,7 @@
 module Securial
   module Helpers
     module KeyTransformer
-      module_function
+      extend self
 
       def camelize(str, format)
         case format

data/lib/securial/helpers/normalizing_helper.rb

@@ -1,7 +1,7 @@
 module Securial
   module Helpers
     module NormalizingHelper
-      module_function
+      extend self
 
       def normalize_email_address(email)
         return "" if email.empty?

data/lib/securial/helpers/regex_helper.rb

@@ -5,14 +5,13 @@ module Securial
       USERNAME_REGEX = /\A(?![0-9])[a-zA-Z](?:[a-zA-Z0-9]|[._](?![._]))*[a-zA-Z0-9]\z/
       PASSWORD_REGEX = %r{\A(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[^a-zA-Z0-9])[a-zA-Z].*\z}
 
-      class << self
-        def valid_email?(email)
-          email.match?(EMAIL_REGEX)
-        end
+      extend self
+      def valid_email?(email)
+        email.match?(EMAIL_REGEX)
+      end
 
-        def valid_username?(username)
-          username.match?(USERNAME_REGEX)
-        end
+      def valid_username?(username)
+        username.match?(USERNAME_REGEX)
       end
     end
   end

data/lib/securial/helpers/roles_helper.rb

@@ -3,14 +3,13 @@ module Securial
     module RolesHelper
       # This module provides helper methods related to roles.
       # It can be extended with additional role-related functionality as needed.
-      class << self
-        def protected_namespace
-          Securial.configuration.admin_role.to_s.strip.underscore.pluralize
-        end
+      extend self
+      def protected_namespace
+        Securial.configuration.admin_role.to_s.strip.underscore.pluralize
+      end
 
-        def titleized_admin_role
-          Securial.configuration.admin_role.to_s.strip.titleize
-        end
+      def titleized_admin_role
+        Securial.configuration.admin_role.to_s.strip.titleize
       end
     end
   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) }