securial 1.0.1 → 1.0.3

data/lib/securial/middleware/transform_response_keys.rb

@@ -1,15 +1,76 @@
+# @title Securial Transform Response Keys Middleware
+#
+# Rack middleware for transforming JSON response keys to client-preferred formats.
+#
+# This middleware automatically converts outgoing JSON response keys from Ruby's
+# snake_case convention to the configured format (camelCase, PascalCase, etc.) to
+# match client application expectations. It only processes JSON responses and
+# preserves the original response structure and content.
+#
+# @example Adding middleware to Rails application
+#   # config/application.rb
+#   config.middleware.use Securial::Middleware::TransformResponseKeys
+#
+# @example Response transformation with lowerCamelCase
+#   # Original Rails response:
+#   { "user_name": "john", "email_address": "john@example.com" }
+#
+#   # Transformed for client:
+#   { "userName": "john", "emailAddress": "john@example.com" }
+#
+# @example Response transformation with UpperCamelCase
+#   # Configuration: config.response_keys_format = :UpperCamelCase
+#   # Original: { "user_profile": { "first_name": "John" } }
+#   # Transformed: { "UserProfile": { "FirstName": "John" } }
+#
+require "json"
+
 module Securial
   module Middleware
-    # This middleware transforms response keys to a specified format.
-    # It uses the KeyTransformer helper to apply the transformation.
+    # Rack middleware that transforms JSON response keys to configured format.
+    #
+    # This middleware enables Rails applications to output responses in
+    # the naming convention expected by client applications (JavaScript,
+    # mobile apps, etc.) while maintaining Ruby's snake_case internally.
     #
-    # It reads the response body if the content type is JSON and transforms
-    # the keys to the specified format (default is lowerCamelCase).
     class TransformResponseKeys
+      # Initializes the middleware with the Rack application and optional format.
+      #
+      # The format parameter is deprecated in favor of the global configuration
+      # setting `Securial.configuration.response_keys_format`.
+      #
+      # @param [#call] app The Rack application to wrap
+      # @param [Symbol] format Deprecated: The key format to use (defaults to :lowerCamelCase)
+      #
+      # @example
+      #   middleware = TransformResponseKeys.new(app)
+      #
+      # @deprecated Use `Securial.configuration.response_keys_format` instead of format parameter
+      #
       def initialize(app, format: :lowerCamelCase)
         @app = app
       end
 
+      # Processes the response and transforms JSON keys if applicable.
+      #
+      # Intercepts JSON responses, parses the body, transforms all keys to
+      # the configured format using the KeyTransformer helper, and replaces
+      # the response body with the transformed JSON. Non-JSON responses
+      # pass through unchanged.
+      #
+      # @param [Hash] env The Rack environment hash
+      # @return [Array] The Rack response array [status, headers, body] with transformed keys
+      #
+      # @example JSON transformation
+      #   # Original response: { "first_name": "John", "last_name": "Doe" }
+      #   # Transformed response: { "firstName": "John", "lastName": "Doe" }
+      #
+      # @example Non-JSON responses
+      #   # HTML, XML, and other content types pass through unchanged
+      #
+      # @example Empty or malformed JSON handling
+      #   # Empty responses and invalid JSON are left unchanged
+      #
       def call(env)
         status, headers, response = @app.call(env)
 
@@ -33,10 +94,29 @@ module Securial
 
       private
 
+      # Checks if the response contains JSON content.
+      #
+      # @param [Hash] headers The response headers hash
+      # @return [Boolean] true if the response has JSON content type
+      # @api private
+      #
       def json_response?(headers)
         headers["Content-Type"]&.include?("application/json")
       end
 
+      # Extracts the complete response body from the response object.
+      #
+      # Iterates through the response body parts and concatenates them
+      # into a single string for JSON parsing and transformation.
+      #
+      # @param [#each] response The response body object (responds to #each)
+      # @return [String] The complete response body as a string
+      # @api private
+      #
+      # @example
+      #   body = extract_body(response)
+      #   # => '{"user_name":"john","email":"john@example.com"}'
+      #
       def extract_body(response)
         response_body = ""
         response.each { |part| response_body << part }

data/lib/securial/middleware.rb

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

data/lib/securial/security/request_rate_limiter.rb

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

data/lib/securial/security.rb

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

data/lib/securial/version.rb

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

data/lib/securial.rb

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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: securial
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.3
 platform: ruby
 authors:
 - Aly Badawy
 bindir: bin
 cert_chain: []
-date: 2025-06-24 00:00:00.000000000 Z
+date: 2025-06-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -96,6 +96,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- ".yardopts"
 - MIT-LICENSE
 - README.md
 - Rakefile
@@ -205,22 +206,27 @@ homepage: https://github.com/AlyBadawy/Securial/wiki
 licenses:
 - MIT
 metadata:
-  release_date: '2025-06-24'
-  allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/AlyBadawy/Securial/wiki
+  release_date: '2025-06-27'
+  allowed_push_host: https://rubygems.org
   source_code_uri: https://github.com/AlyBadawy/Securial
+  documentation_uri: https://alybadawy.github.io/Securial/_index.html
   changelog_uri: https://github.com/AlyBadawy/Securial/blob/main/CHANGELOG.md
-post_install_message: "\n    ---\n    [SECURIAL] Thank you for installing Securial!\n\n
-  \   Securial is a mountable Rails engine that provides robust, extensible\n    authentication
-  and access control for Rails applications. It supports JWT,\n    API tokens, session-based
-  auth, and is designed for easy integration with\n    modern web and mobile apps.\n\n
-  \   Usage:\n      securial new APP_NAME [rails_options...]    # Create a new Rails
-  app with Securial pre-installed\n      securial -v, --version                      #
-  Show the Securial gem version\n      securial -h, --help                         #
-  Show this help message\n\n    Example:\n      securial new myapp --api --database=postgresql
-  -T\n\n    More Info:\n      review the [changelog] and [WIKI] for more info on the
-  latest\n      changes and how to use this gem/engine:\n        [Changelog]:  https://github.com/AlyBadawy/Securial/blob/main/CHANGELOG.md\n
-  \       [WIKI]:       https://github.com/AlyBadawy/Securial/wiki\n    ---\n  "
+  wiki_uri: https://github.com/AlyBadawy/Securial/wiki
+post_install_message: "\e[36m\n ▗▄▄▖▗▄▄▄▖ ▗▄▄▖▗▖ ▗▖▗▄▄▖ ▗▄▄▄▖ ▗▄▖ ▗▖\n▐▌   ▐▌   ▐▌
+  \  ▐▌ ▐▌▐▌ ▐▌  █  ▐▌ ▐▌▐▌\n ▝▀▚▖▐▛▀▀▘▐▌   ▐▌ ▐▌▐▛▀▚▖  █  ▐▛▀▜▌▐▌\n▗▄▄▞▘▐▙▄▄▖▝▚▄▄▖▝▚▄▞▘▐▌
+  ▐▌▗▄█▄▖▐▌ ▐▌▐▙▄▄▖\n\e[0m\n\n\e[32mThank you for installing Securial!\e[0m\n\n\e[37mSecurial
+  is a mountable Rails engine that provides robust, extensible\nauthentication and
+  access control for Rails applications. It supports JWT,\nAPI tokens, session-based
+  auth, and is designed for easy integration with\nmodern web and mobile apps.\e[0m\n\n\e[33mUsage:\e[0m\n
+  \ \e[36msecurial new APP_NAME [rails_options...]\e[0m    # Create a new Rails app
+  with Securial pre-installed\n  \e[36msecurial -v, --version\e[0m                      #
+  Show the Securial gem version\n  \e[36msecurial -h, --help\e[0m                         #
+  Show this help message\n\n\e[33mExample:\e[0m\n  \e[32msecurial new myapp --api
+  --database=postgresql -T\e[0m\n\n\e[33mMore Info:\e[0m\n  \e[37mreview the [changelog]
+  and [WIKI] for more info on the latest\n  changes and how to use this gem/engine:\e[0m\n
+  \   \e[34m[Changelog]:  https://github.com/AlyBadawy/Securial/blob/main/CHANGELOG.md\e[0m\n
+  \   \e[34m[WIKI]:       https://github.com/AlyBadawy/Securial/wiki\e[0m\n\e[90m---\e[0m\n"
 rdoc_options: []
 require_paths:
 - lib