securial 1.0.1 → 1.0.3

data/lib/securial/config/signature.rb

@@ -1,14 +1,74 @@
+# @title Securial Configuration Signature
+#
+# Configuration schema definition and validation rules for the Securial framework.
+#
+# This module defines the complete configuration schema for Securial, including
+# all available configuration options, their types, default values, and validation
+# rules. It serves as the single source of truth for what configuration options
+# are available and how they should be validated.
+#
+# @example Getting the complete configuration schema
+#   schema = Securial::Config::Signature.config_signature
+#   # => { app_name: { type: String, required: true, default: "Securial" }, ... }
+#
+# @example Getting default configuration values
+#   defaults = Securial::Config::Signature.default_config_attributes
+#   # => { app_name: "Securial", log_to_file: true, ... }
+#
 module Securial
   module Config
+    # Configuration schema definition and validation rules.
+    #
+    # This module provides the complete schema for Securial's configuration system,
+    # defining all available options, their types, validation rules, and default values.
+    # It's used by the configuration system to validate user-provided settings.
+    #
     module Signature
-      LOG_LEVELS         = %i[debug info warn error fatal unknown].freeze
+      # Valid log levels for the logging system.
+      #
+      # @return [Array<Symbol>] Available log levels from least to most severe
+      #
+      LOG_LEVELS = %i[debug info warn error fatal unknown].freeze
+
+      # Supported JWT signing algorithms for session tokens.
+      #
+      # @return [Array<Symbol>] HMAC algorithms supported for JWT signing
+      #
       SESSION_ALGORITHMS = %i[hs256 hs384 hs512].freeze
-      SECURITY_HEADERS   = %i[strict default none].freeze
-      TIMESTAMP_OPTIONS  = %i[all admins_only none].freeze
+
+      # Security header configuration options.
+      #
+      # @return [Array<Symbol>] Available security header policies
+      #
+      SECURITY_HEADERS = %i[strict default none].freeze
+
+      # Timestamp inclusion options for API responses.
+      #
+      # @return [Array<Symbol>] Who should see timestamps in responses
+      #
+      TIMESTAMP_OPTIONS = %i[all admins_only none].freeze
+
+      # Available key format transformations for API responses.
+      #
+      # @return [Array<Symbol>] Supported key case formats
+      #
       RESPONSE_KEYS_FORMATS = %i[snake_case lowerCamelCase UpperCamelCase].freeze
 
       extend self
 
+      # Returns the complete configuration schema for Securial.
+      #
+      # Combines all configuration sections into a single schema hash that defines
+      # every available configuration option, its type, validation rules, and
+      # default value.
+      #
+      # @return [Hash] Complete configuration schema with validation rules
+      #
+      # @example
+      #   schema = config_signature
+      #   app_name_config = schema[:app_name]
+      #   # => { type: String, required: true, default: "Securial" }
+      #
       def config_signature
         [
           general_signature,
@@ -22,6 +82,18 @@ module Securial
         ].reduce({}, :merge)
       end
 
+      # Extracts default values from the configuration schema.
+      #
+      # Transforms the complete configuration schema to return only the default
+      # values for each configuration option, suitable for initializing a new
+      # configuration instance.
+      #
+      # @return [Hash] Default values for all configuration options
+      #
+      # @example
+      #   defaults = default_config_attributes
+      #   # => { app_name: "Securial", session_expiration_duration: 3.minutes, ... }
+      #
       def default_config_attributes
         config_signature.transform_values do |options|
           options[:default]
@@ -30,12 +102,22 @@ module Securial
 
       private
 
+      # General application configuration options.
+      #
+      # @return [Hash] Schema for general application settings
+      # @api private
+      #
       def general_signature
         {
           app_name: { type: String, required: true, default: "Securial" },
         }
       end
 
+      # Logging system configuration options.
+      #
+      # @return [Hash] Schema for logging configuration
+      # @api private
+      #
       def logger_signature
         {
           log_to_file: { type: [TrueClass, FalseClass], required: true, default: Rails.env.test? ? false : true },
@@ -45,12 +127,22 @@ module Securial
         }
       end
 
+      # User role and permission configuration options.
+      #
+      # @return [Hash] Schema for role management settings
+      # @api private
+      #
       def roles_signature
         {
           admin_role: { type: Symbol, required: true, default: :admin },
         }
       end
 
+      # Session and JWT token configuration options.
+      #
+      # @return [Hash] Schema for session management settings
+      # @api private
+      #
       def session_signature
         {
           session_expiration_duration: { type: ActiveSupport::Duration, required: true, default: 3.minutes },
@@ -60,6 +152,11 @@ module Securial
         }
       end
 
+      # Email and notification configuration options.
+      #
+      # @return [Hash] Schema for mailer settings
+      # @api private
+      #
       def mailer_signature
         {
           mailer_sender: { type: String, required: true, default: "no-reply@example.com" },
@@ -73,6 +170,11 @@ module Securial
         }
       end
 
+      # Password policy and security configuration options.
+      #
+      # @return [Hash] Schema for password management settings
+      # @api private
+      #
       def password_signature
         {
           password_min_length: { type: Numeric, required: true, default: 8 },
@@ -85,14 +187,23 @@ module Securial
         }
       end
 
+      # API response formatting configuration options.
+      #
+      # @return [Hash] Schema for response formatting settings
+      # @api private
+      #
       def response_signature
         {
-          response_keys_format: { type: Symbol, required: true, allowed_values:
-            RESPONSE_KEYS_FORMATS, default: :snake_case, },
+          response_keys_format: { type: Symbol, required: true, allowed_values: RESPONSE_KEYS_FORMATS, default: :snake_case },
           timestamps_in_response: { type: Symbol, required: true, allowed_values: TIMESTAMP_OPTIONS, default: :all },
         }
       end
 
+      # Security and rate limiting configuration options.
+      #
+      # @return [Hash] Schema for security settings
+      # @api private
+      #
       def security_signature
         {
           security_headers: { type: Symbol, required: true, allowed_values: SECURITY_HEADERS, default: :strict },

data/lib/securial/config/validation.rb

@@ -1,9 +1,51 @@
+# @title Securial Configuration Validation
+#
+# Configuration validation utilities for the Securial framework.
+#
+# This module provides comprehensive validation for Securial configuration settings,
+# ensuring that all required fields are present, types are correct, values are within
+# acceptable ranges, and cross-field dependencies are satisfied. It validates against
+# the schema defined in Securial::Config::Signature.
+#
+# @example Validating a configuration object
+#   config = Securial::Configuration.new
+#   begin
+#     Securial::Config::Validation.validate_all!(config)
+#   rescue Securial::Error::Config::InvalidConfigurationError => e
+#     Rails.logger.error("Configuration error: #{e.message}")
+#   end
+#
 require "securial/logger"
 
 module Securial
   module Config
+    # Configuration validation and verification utilities.
+    #
+    # This module provides methods to validate Securial configuration objects
+    # against the defined schema, ensuring type safety, required field presence,
+    # and business logic constraints are met before the application starts.
+    #
     module Validation
       extend self
+
+      # Validates all configuration settings against the schema.
+      #
+      # Performs comprehensive validation of the provided configuration object,
+      # including required field checks, type validation, value constraints,
+      # and cross-field dependency validation.
+      #
+      # @param [Securial::Configuration] securial_config The configuration object to validate
+      # @return [void]
+      # @raise [Securial::Error::Config::InvalidConfigurationError] If any validation fails
+      #
+      # @example
+      #   config = Securial::Configuration.new
+      #   config.app_name = "MyApp"
+      #   config.session_secret = "my-secret-key"
+      #
+      #   Validation.validate_all!(config)
+      #   # Configuration is valid and ready to use
+      #
       def validate_all!(securial_config)
         signature = Securial::Config::Signature.config_signature
 
@@ -14,13 +56,26 @@ module Securial
 
       private
 
+      # Validates that all required configuration fields are present.
+      #
+      # Checks both unconditionally required fields and conditionally required
+      # fields based on other configuration values.
+      #
+      # @param [Hash] signature The configuration schema from Signature
+      # @param [Securial::Configuration] config The configuration object to validate
+      # @return [void]
+      # @raise [Securial::Error::Config::InvalidConfigurationError] If required fields are missing
+      # @api private
+      #
       def validate_required_fields!(signature, config)
         signature.each do |key, options|
           value = config.send(key)
           required = options[:required]
+
           if required == true && value.nil?
             raise_error("#{key} is required but not provided.")
           elsif required.is_a?(String)
+            # Handle conditional requirements based on other config values
             dynamic_required = config.send(required)
             signature[key][:required] = dynamic_required
             if dynamic_required && value.nil?
@@ -30,36 +85,72 @@ module Securial
         end
       end
 
+      # Validates types and value constraints for configuration fields.
+      #
+      # Ensures that configuration values match their expected types and fall
+      # within acceptable ranges or allowed value sets.
+      #
+      # @param [Hash] signature The configuration schema from Signature
+      # @param [Securial::Configuration] config The configuration object to validate
+      # @return [void]
+      # @raise [Securial::Error::Config::InvalidConfigurationError] If types or values are invalid
+      # @api private
+      #
       def validate_types_and_values!(signature, config)
         signature.each do |key, options|
           next unless signature[key][:required]
+
           value = config.send(key)
           types = Array(options[:type])
 
+          # Type validation
           unless types.any? { |type| value.is_a?(type) }
             raise_error("#{key} must be of type(s) #{types.join(', ')}, but got #{value.class}.")
           end
 
+          # Duration-specific validation
           if options[:type] == ActiveSupport::Duration && value <= 0
             raise_error("#{key} must be a positive duration, but got #{value}.")
           end
 
+          # Numeric value validation
           if options[:type] == Numeric && value < 0
             raise_error("#{key} must be a non-negative numeric value, but got #{value}.")
           end
 
+          # Allowed values validation
           if options[:allowed_values] && options[:allowed_values].exclude?(value)
             raise_error("#{key} must be one of #{options[:allowed_values].join(', ')}, but got #{value}.")
           end
         end
       end
 
+      # Validates password length configuration constraints.
+      #
+      # Ensures that password minimum length does not exceed maximum length,
+      # which would create an impossible constraint for users.
+      #
+      # @param [Securial::Configuration] config The configuration object to validate
+      # @return [void]
+      # @raise [Securial::Error::Config::InvalidConfigurationError] If password lengths are invalid
+      # @api private
+      #
       def validate_password_lengths!(config)
         if config.password_min_length > config.password_max_length
           raise_error("password_min_length cannot be greater than password_max_length.")
         end
       end
 
+      # Logs error message and raises configuration error.
+      #
+      # Provides a consistent way to handle validation failures by logging
+      # the error at fatal level and raising the appropriate exception.
+      #
+      # @param [String] msg The error message to log and include in the exception
+      # @return [void]
+      # @raise [Securial::Error::Config::InvalidConfigurationError] Always raises with the provided message
+      # @api private
+      #
       def raise_error(msg)
         Securial.logger.fatal msg
         raise Securial::Error::Config::InvalidConfigurationError, msg

data/lib/securial/config.rb

@@ -1,16 +1,52 @@
+# @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
   extend self
-  attr_accessor :configuration
 
+  # 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
 
+  # 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
@@ -20,8 +56,19 @@ module Securial
     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,17 +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)
         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")
       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