securial 1.0.0 → 1.0.2

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,15 +1,55 @@
+# @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
-  class << self
-    attr_accessor :logger
+  extend self
+  attr_accessor :logger
 
-    def logger
-      @logger ||= Logger::Builder.build
-    end
+  # 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 ||= Securial::Logger::Builder.build
+  end
 
-    def logger=(logger)
-      @logger = logger
-    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
 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
-      module_function
+      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.0".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
-  class << self
-    delegate :protected_namespace, to: Securial::Helpers::RolesHelper
-    delegate :titleized_admin_role, to: Securial::Helpers::RolesHelper
-  end
+  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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: securial
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - Aly Badawy
 bindir: bin
 cert_chain: []
-date: 2025-06-18 00:00:00.000000000 Z
+date: 2025-06-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -55,16 +55,22 @@ dependencies:
   name: jwt
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: '3.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: '3.2'
 - !ruby/object:Gem::Dependency
   name: rack-attack
   requirement: !ruby/object:Gem::Requirement
@@ -90,6 +96,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - MIT-LICENSE
 - README.md
 - Rakefile
@@ -161,10 +168,7 @@ files:
 - lib/securial/auth/auth_encoder.rb
 - lib/securial/auth/session_creator.rb
 - lib/securial/auth/token_generator.rb
-- lib/securial/cli/run.rb
-- lib/securial/cli/securial_new.rb
-- lib/securial/cli/show_help.rb
-- lib/securial/cli/show_version.rb
+- lib/securial/cli.rb
 - lib/securial/config.rb
 - lib/securial/config/configuration.rb
 - lib/securial/config/signature.rb
@@ -202,7 +206,7 @@ homepage: https://github.com/AlyBadawy/Securial/wiki
 licenses:
 - MIT
 metadata:
-  release_date: '2025-06-18'
+  release_date: '2025-06-25'
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/AlyBadawy/Securial/wiki
   source_code_uri: https://github.com/AlyBadawy/Securial

data/lib/securial/cli/run.rb

@@ -1,11 +0,0 @@
-# rubocop:disable Rails/Output
-def run(command, chdir: nil)
-  puts "→ #{command}"
-  if chdir
-    Dir.chdir(chdir) do
-      system(command) || abort("❌ Command failed: #{command}")
-    end
-  else
-    system(command) || abort("❌ Command failed: #{command}")
-  end
-end

data/lib/securial/cli/securial_new.rb

@@ -1,53 +0,0 @@
-# rubocop:disable Rails/Output
-require_relative "run"
-
-def securial_new(app_name, rails_options)
-  puts "🏗️  Creating new Rails app: #{app_name}"
-  create_rails_app(app_name, rails_options)
-  add_securial_gem(app_name)
-  install_gems(app_name)
-  install_securial(app_name)
-  mount_securial_engine(app_name)
-  print_final_instructions(app_name)
-end
-
-def create_rails_app(app_name, rails_options)
-  rails_command = ["rails", "new", app_name, *rails_options].join(" ")
-  run(rails_command)
-end
-
-def add_securial_gem(app_name)
-  puts "📦  Adding Securial gem to Gemfile"
-  gemfile_path = File.join(app_name, "Gemfile")
-  File.open(gemfile_path, "a") { |f| f.puts "\ngem 'securial'" }
-end
-
-def install_gems(app_name)
-  run("bundle install", chdir: app_name)
-end
-
-def install_securial(app_name)
-  puts "🔧  Installing Securial"
-  run("bin/rails generate securial:install", chdir: app_name)
-  run("bin/rails db:migrate", chdir: app_name)
-end
-
-def mount_securial_engine(app_name)
-  puts "🔗  Mounting Securial engine in routes"
-  routes_path = File.join(app_name, "config/routes.rb")
-  routes = File.read(routes_path)
-  updated = routes.sub("Rails.application.routes.draw do") do |match|
-    "#{match}\n  mount Securial::Engine => '/securial'"
-  end
-  File.write(routes_path, updated)
-end
-
-def print_final_instructions(app_name)
-  puts "🎉  Securial has been successfully installed in your Rails app!"
-  puts "✅  Your app is ready at: ./#{app_name}"
-  puts ""
-  puts "➡️  Next steps:"
-  puts "    cd #{app_name}"
-  puts "⚙️  Optional: Configure Securial in config/initializers/securial.rb"
-  puts "    rails server"
-end

data/lib/securial/cli/show_help.rb

@@ -1,26 +0,0 @@
-# rubocop:disable Rails/Output
-def show_help
-  puts <<~HELP
-    Securial CLI
-
-    Securial is a mountable Rails engine that provides robust, extensible
-    authentication and access control for Rails applications. It supports JWT,
-    API tokens, session-based auth, and is designed for easy integration with
-    modern web and mobile apps.
-
-    Usage:
-      securial new APP_NAME [rails_options...]    # Create a new Rails app with Securial pre-installed
-      securial -v, --version                      # Show the Securial gem version
-      securial -h, --help                         # Show this help message
-
-    Example:
-      securial new myapp --api --database=postgresql -T
-
-    More Info:
-      review the [Changelog] and [WIKI] for more info on the latest
-      changes and how to use this gem/engine:
-        [Changelog]:  https://github.com/AlyBadawy/Securial/blob/main/CHANGELOG.md
-        [WIKI]:       https://github.com/AlyBadawy/Securial/wiki
-
-  HELP
-end

data/lib/securial/cli/show_version.rb

@@ -1,9 +0,0 @@
-# rubocop:disable Rails/Output
-def show_version
-  begin
-    require "securial/version"
-    puts "Securial v#{Securial::VERSION}"
-  rescue LoadError
-    puts "Securial version information not available."
-  end
-end