securial 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9f93334f493089fe07b825a71ccbe4c8eb2b3ae9b924e2e7cab16f4818d0bb4a
-  data.tar.gz: 47e73ee83002a71737e3d7e16c31fe428652ddb9a6d4104eb2d622b9bc9dc666
+  metadata.gz: 9d961941c8221da3b247295215f1103d8321ae910dc7b0e3d5c1bff743e5bc3b
+  data.tar.gz: ffa192fdfc0060e769a635063a4f326ebcf1a720fb94d8304784328675dc6338
 SHA512:
-  metadata.gz: 3108d25afcf5df41d3f7578b12fdb496402deb3ba7ce9e8485ed90e96e3d71dd7d4297c67dd49911d73ffd2a31100845e792e5e1670d3a35cbe877bad8066ba6
-  data.tar.gz: 1c403ba8a424348b2ac80c0a46c7cc71e9e720bff838a735caac6d263884c3eab06480917d3bff8c8f7a7ed295bc4ecac1e5cf53caf609c361aa2a5159533e0e
+  metadata.gz: 84646cb2e5ed9a96f4f46baa4971086e62b7d8628e436c04e1a7ec30d6f772e74563d76163b933bd1c9d760620f763b9d96cf0bdfe1a1c43337155a8a85b1410
+  data.tar.gz: 4103a16e922ca508481402fd9492587ab71aed2604abea521b0f6a1ab8a6d42b576258540d02ec5a080e2f0becc60b8cf6229be19a203604e22984ec70bd30eb

data/README.md

@@ -1,14 +1,16 @@
 # Securial Gem
 
 [![Gem Version](https://img.shields.io/gem/v/securial?logo=rubygems&logoColor=ffffff&logoSize=auto&label=version&color=violet&cacheSeconds=120)](https://rubygems.org/gems/securial)
-[![Gem Downloads](https://img.shields.io/gem/dt/securial.svg)](https://rubygems.org/gems/securial)
-[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/AlyBadawy/Securial?tab=MIT-1-ov-file#readme)
-
+[![Downloads](https://img.shields.io/gem/dt/securial.svg)](https://rubygems.org/gems/securial)
 [![Tests](https://github.com/alybadawy/securial/actions/workflows/ci.yml/badge.svg)](https://github.com/alybadawy/securial/actions)
 [![Coveralls](https://img.shields.io/coverallsCoverage/github/AlyBadawy/Securial?branch=main&logo=coveralls&logoColor=%233F5767&labelColor=ddeedd)
 ](https://coveralls.io/github/AlyBadawy/Securial?branch=main)
 
-[![Documentation](https://img.shields.io/badge/yard-Documentation-blue?style=flat&logo=readthedocs&logoColor=%238CA1AF&label=yard&link=https%3A%2F%2Fwww.rubydoc.info%2Fgems%2Fsecurial%2Findex)](https://alybadawy.github.io/Securial/_index.html)
+
+[![License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/AlyBadawy/Securial?tab=MIT-1-ov-file#readme)
+[![Documentation](https://img.shields.io/badge/yard-Documentation-cyan?style=flat&logo=readthedocs&logoColor=%238CA1AF&label=yard)](https://alybadawy.github.io/Securial/_index.html)
+[![Wiki](https://img.shields.io/badge/Wiki-Github_Wiki-orange?style=flat&logo=wikibooks&logoColor=%23F5CD0E&label=Wiki)](https://github.com/alybadawy/securial/wiki)
+
 
 ---
 

data/lib/securial/auth/auth_encoder.rb

@@ -1,10 +1,58 @@
+# @title Securial Authentication Token Encoder
+#
+# JWT token encoding and decoding for session authentication.
+#
+# This module provides secure JWT token creation and validation for user sessions
+# in the Securial authentication system. It handles the encoding of session data
+# into JWT tokens and the secure decoding/validation of those tokens, including
+# signature verification and claim validation.
+#
+# @example Encoding a session into a JWT token
+#   session = Securial::Session.find(session_id)
+#   token = Securial::Auth::AuthEncoder.encode(session)
+#   # => "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIxMjM0NTY3ODkwIiwic3ViIjoiM..."
+#
+# @example Decoding and validating a JWT token
+#   begin
+#     payload = Securial::Auth::AuthEncoder.decode(token)
+#     session_id = payload['jti']
+#     # Use session_id to retrieve session from database
+#   rescue Securial::Error::Auth::TokenDecodeError => e
+#     # Handle invalid token
+#   end
 require "jwt"
 
 module Securial
   module Auth
+    # Handles JWT token encoding and decoding for session authentication.
+    #
+    # This module provides methods to securely encode session information into
+    # JWT tokens and decode/validate those tokens. It uses HMAC signing with
+    # a configurable secret and includes standard JWT claims for security.
+    #
+    # The tokens include:
+    # - Session ID (jti claim) for session lookup
+    # - Expiration time (exp claim) for automatic invalidation
+    # - Subject (sub claim) identifying the token type
+    # - Custom claims for IP address and user agent validation
+    #
+    # @see https://datatracker.ietf.org/doc/html/rfc7519 JWT RFC
     module AuthEncoder
       extend self
 
+      # Encodes a session object into a signed JWT token.
+      #
+      # Creates a JWT token containing the session ID and metadata for later
+      # validation. The token is signed using the configured secret and algorithm.
+      #
+      # @param [Securial::Session] session The session object to encode
+      # @return [String, nil] The encoded JWT token, or nil if session is invalid
+      # @raise [Securial::Error::Auth::TokenEncodeError] If JWT encoding fails
+      #
+      # @example
+      #   session = Securial::Session.create!(user: current_user)
+      #   token = AuthEncoder.encode(session)
+      #   # => "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIxMjM0NTY3ODkw..."
       def encode(session)
         return nil unless session && session.class == Securial::Session
 
@@ -28,6 +76,21 @@ module Securial
         end
       end
 
+      # Decodes and validates a JWT token, returning the payload.
+      #
+      # Verifies the token signature, expiration, and other claims before
+      # returning the decoded payload. The token must have been signed with
+      # the current secret and must not be expired.
+      #
+      # @param [String] token The JWT token to decode and validate
+      # @return [Hash] The decoded token payload containing session information
+      # @raise [Securial::Error::Auth::TokenDecodeError] If token is invalid, expired, or malformed
+      #
+      # @example
+      #   payload = AuthEncoder.decode("eyJhbGciOiJIUzI1NiJ9...")
+      #   session_id = payload['jti']
+      #   ip_address = payload['ip']
+      #   user_agent = payload['agent']
       def decode(token)
         begin
           decoded = ::JWT.decode(token, secret, true, { algorithm: algorithm, verify_jti: true, iss: "securial" })
@@ -39,14 +102,29 @@ module Securial
 
       private
 
+      # Returns the secret key used for JWT signing and verification.
+      #
+      # @return [String] The configured session secret
+      # @api private
+      #
       def secret
         Securial.configuration.session_secret
       end
 
+      # Returns the algorithm used for JWT signing.
+      #
+      # @return [String] The configured session algorithm in uppercase
+      # @api private
+      #
       def algorithm
         Securial.configuration.session_algorithm.to_s.upcase
       end
 
+      # Returns the token expiration duration.
+      #
+      # @return [ActiveSupport::Duration] The configured session expiration duration
+      # @api private
+      #
       def expiry_duration
         Securial.configuration.session_expiration_duration
       end

data/lib/securial/auth/session_creator.rb

@@ -1,8 +1,57 @@
+# @title Securial Session Creator
+#
+# Session creation utilities for the Securial authentication system.
+#
+# This module provides functionality to create authenticated user sessions with
+# proper token generation and metadata tracking. It handles the validation of
+# user and request objects before creating database records and setting up
+# the current session context.
+#
+# @example Creating a session for a user
+#   user = Securial::User.find_by(email: "user@example.com")
+#   session = Securial::Auth::SessionCreator.create_session!(user, request)
+#   # => #<Securial::Session id: "abc123", user_id: "user123", ...>
+#
+# @example Handling invalid inputs
+#   invalid_session = Securial::Auth::SessionCreator.create_session!(nil, request)
+#   # => nil
 module Securial
   module Auth
+    # Creates and manages user authentication sessions.
+    #
+    # This module provides methods to create new authenticated sessions for users,
+    # including proper validation of inputs, generation of refresh tokens, and
+    # setting up session metadata such as IP addresses and user agents.
+    #
+    # Created sessions are automatically set as the current session context and
+    # include all necessary tokens and expiration information for secure
+    # authentication management.
+    #
     module SessionCreator
       extend self
 
+      # Creates a new authenticated session for the given user and request.
+      #
+      # Validates the provided user and request objects, then creates a new session
+      # record with appropriate metadata and tokens. The newly created session is
+      # automatically set as the current session context.
+      #
+      # @param [Securial::User] user The user object to create a session for
+      # @param [ActionDispatch::Request] request The HTTP request object containing metadata
+      # @return [Securial::Session, nil] The created session object, or nil if validation fails
+      #
+      # @example Creating a session after successful authentication
+      #   user = Securial::User.authenticate(email, password)
+      #   if user
+      #     session = SessionCreator.create_session!(user, request)
+      #     # User is now authenticated with active session
+      #   end
+      #
+      # @example Handling validation failures
+      #   # Invalid user (not persisted)
+      #   new_user = Securial::User.new
+      #   session = SessionCreator.create_session!(new_user, request)
+      #   # => nil
       def create_session!(user, request)
         valid_user = user && user.is_a?(Securial::User) && user.persisted?
         valid_request = request.is_a?(ActionDispatch::Request)

data/lib/securial/auth/token_generator.rb

@@ -1,11 +1,48 @@
+# @title Securial Token Generator
+#
+# Secure token generation utilities for the Securial authentication system.
+#
+# This module provides cryptographically secure token generation for various
+# authentication purposes, including refresh tokens and password reset tokens.
+# All tokens are generated using secure random sources and include appropriate
+# entropy for their intended use cases.
+#
+# @example Generating a refresh token
+#   refresh_token = Securial::Auth::TokenGenerator.generate_refresh_token
+#   # => "a1b2c3d4e5f6...9876543210abcdef1234567890"
+#
+# @example Generating a password reset token
+#   reset_token = Securial::Auth::TokenGenerator.generate_password_reset_token
+#   # => "aBc123-DeF456"
+#
 require "openssl"
 require "securerandom"
 
 module Securial
   module Auth
+    # Generates secure tokens for authentication operations.
+    #
+    # This module provides methods to generate cryptographically secure tokens
+    # for different authentication scenarios. All tokens use secure random
+    # generation and appropriate cryptographic techniques to ensure uniqueness
+    # and security.
     module TokenGenerator
       extend self
 
+      # Generates a secure refresh token using HMAC and random data.
+      #
+      # Creates a refresh token by combining an HMAC signature with random data,
+      # providing both integrity verification and sufficient entropy. The token
+      # is suitable for long-term storage and session refresh operations.
+      #
+      # @return [String] A secure refresh token (96 characters hexadecimal)
+      #
+      # @example
+      #   token = TokenGenerator.generate_refresh_token
+      #   # => "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456789012345678901234567890abcdef"
+      #
+      # @see #generate_password_reset_token
+      #
       def generate_refresh_token
         secret = Securial.configuration.session_secret
         algo = "SHA256"
@@ -17,10 +54,47 @@ module Securial
         "#{hmac}#{random_data}"
       end
 
+      # Generates a user-friendly password reset token.
+      #
+      # Creates a short, alphanumeric token formatted for easy user entry.
+      # The token is suitable for password reset flows where users need to
+      # manually enter the token from an email or SMS message.
+      #
+      # @return [String] A formatted password reset token (format: "ABC123-DEF456")
+      #
+      # @example
+      #   token = TokenGenerator.generate_password_reset_token
+      #   # => "aBc123-DeF456"
+      #
+      # @note This token has lower entropy than refresh tokens and should have
+      #   shorter expiration times and rate limiting protection.
+      #
+      # @see #generate_refresh_token
+      #
       def generate_password_reset_token
         token = SecureRandom.alphanumeric(12)
         "#{token[0, 6]}-#{token[6, 6]}"
       end
+
+      # Generates a URL-safe friendly token for general use.
+      #
+      # Creates a secure, URL-safe token suitable for various authentication
+      # operations that require a balance between security and usability.
+      #
+      # @param [Integer] length The desired length of the generated token (default: 20)
+      # @return [String] A URL-safe token containing letters, numbers, and safe symbols
+      #
+      # @example
+      #   token = TokenGenerator.friendly_token
+      #   # => "aBcDeF123456GhIjKl78"
+      #
+      # @example With custom length
+      #   token = TokenGenerator.friendly_token(32)
+      #   # => "aBcDeF123456GhIjKl789012MnOpQr34"
+      #
+      def friendly_token(length = 20)
+        SecureRandom.urlsafe_base64(length).tr("lIO0", "sxyz")[0, length]
+      end
     end
   end
 end

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