securial 1.0.1 → 1.0.2

data/app/models/securial/user.rb

@@ -1,4 +1,34 @@
 module Securial
+  #
+  # User
+  #
+  # This class represents a user in the Securial authentication and authorization system.
+  #
+  # Users can have multiple roles assigned to them, which define their permissions
+  # and access levels within the application.
+  #
+  # The User model includes functionality for password reset, email normalization,
+  # and various validations to ensure data integrity.
+  #
+  # ## Attributes
+  # - `email_address`: The user's email address, which is normalized
+  # - `username`: A unique username for the user, with specific format requirements
+  # - `first_name`: The user's first name, required and limited in length
+  # - `last_name`: The user's last name, required and limited in length
+  # - `phone`: An optional phone number, limited in length
+  # - `bio`: An optional biography, limited in length
+  #
+  # ## Validations
+  # - Email address must be present, unique, and formatted correctly
+  # - Username must be present, unique (case insensitive), and formatted correctly
+  # - First and last names must be present and limited in length
+  # - Phone and bio fields are optional but have length restrictions
+  #
+  # ## Associations
+  # - Has many role assignments, allowing users to have multiple roles
+  # - Has many roles through role assignments, enabling flexible permission management
+  # - Has many sessions, allowing for session management and tracking
+  #
   class User < ApplicationRecord
     include Securial::PasswordResettable
 
@@ -45,6 +75,10 @@ module Securial
     has_many :sessions, dependent: :destroy
 
 
+    # Checks if the user has the specified role.
+    #
+    # @param [String] role_name The name of the role to check
+    # @return [Boolean] Returns true if the user has the specified role, false otherwise.
     def is_admin?
       roles.exists?(role_name: Securial.titleized_admin_role)
     end

data/lib/generators/factory_bot/model/model_generator.rb

@@ -1,6 +1,7 @@
 require "rails/generators"
 require "rails/generators/named_base"
 
+# @!ignore
 module FactoryBot
   module Generators
     class ModelGenerator < Rails::Generators::NamedBase

data/lib/securial/auth.rb

@@ -1,12 +1,50 @@
+# @title Securial Authentication System
+#
+# Core authentication components for the Securial framework.
+#
+# This file serves as the entry point for authentication-related functionality in Securial,
+# loading specialized modules that handle token generation, encoding/decoding, and session management.
+# These components work together to provide a secure, flexible authentication system supporting
+# token-based and session-based authentication patterns.
+#
+# @example Encoding a session token
+#   # Create an encoded JWT representing a user session
+#   token = Securial::Auth::AuthEncoder.encode(user_session)
+#   # => "eyJhbGciOiJIUzI1NiJ9.eyJqdGkiOiIxMjM0NTY3ODkwIiwic3ViIjoiM..."
+#
+# @example Creating a new user session
+#   # Authenticate user and create a new session with tokens
+#   Securial::Auth::SessionCreator.create_session!(user, request)
+#
+#   # Access the newly created session
+#   current_session = Current.session
+#
+# @example Generating secure tokens
+#   # Generate a password reset token
+#   reset_token = Securial::Auth::TokenGenerator.friendly_token
+#   # => "aBc123DeF456gHi789"
+#
 require "securial/auth/auth_encoder"
 require "securial/auth/session_creator"
 require "securial/auth/token_generator"
 
 module Securial
-  module Auth
-    # This is a placeholder for the Auth module.
-    # It can be used to include authentication-related methods or constants
-    # that are not specific to encoding or session creation.
-    # Currently, it serves as a namespace for the AuthEncoder and SessionCreator modules.
-  end
+  # Namespace for authentication-related functionality in the Securial framework.
+  #
+  # The Auth module contains components that work together to provide a complete
+  # authentication system for Securial-powered applications:
+  #
+  # - {AuthEncoder} - Handles JWT token encoding and decoding with security measures
+  # - {SessionCreator} - Creates and manages authenticated user sessions
+  # - {TokenGenerator} - Generates secure random tokens for various authentication needs
+  #
+  # These components handle the cryptographic and security aspects of user authentication,
+  # ensuring that best practices are followed for token generation, validation, and session
+  # management throughout the application lifecycle.
+  #
+  # @see Securial::Auth::AuthEncoder
+  # @see Securial::Auth::SessionCreator
+  # @see Securial::Auth::TokenGenerator
+  #
+  module Auth; end
 end

data/lib/securial/cli.rb

@@ -1,13 +1,51 @@
+# @title Securial Command Line Interface
+#
+# Command line interface for the Securial framework.
+#
+# This file implements the CLI tool for Securial, providing command-line utilities
+# for creating new Rails applications with Securial pre-installed. It handles
+# command parsing, option flags, and orchestrates the application setup process.
+#
+# @example Creating a new Rails application with Securial
+#   # Create a basic Securial application
+#   $ securial new myapp
+#
+#   # Create an API-only Securial application with PostgreSQL
+#   $ securial new myapi --api --database=postgresql
+#
 require "optparse"
 
 # rubocop:disable Rails/Exit, Rails/Output
 
 module Securial
+  # Command-line interface for the Securial gem.
+  #
+  # This class provides the command-line functionality for Securial, enabling users
+  # to create new Rails applications with Securial pre-installed and configured.
+  # It handles command parsing, flag processing, and orchestrates the setup of
+  # new applications.
+  #
   class CLI
+    # Entry point for the CLI application.
+    #
+    # Creates a new CLI instance and delegates to its start method.
+    #
+    # @param argv [Array<String>] command line arguments
+    # @return [Integer] exit status code (0 for success, non-zero for errors)
+    #
     def self.start(argv)
       new.start(argv)
     end
 
+    # Processes command line arguments and executes the appropriate action.
+    #
+    # This method handles both option flags (like --version) and commands
+    # (like 'new'), delegating to specialized handlers and returning
+    # the appropriate exit code.
+    #
+    # @param argv [Array<String>] command line arguments
+    # @return [Integer] exit status code (0 for success, non-zero for errors)
+    #
     def start(argv)
       # Process options and exit if a flag was handled
       result = handle_flags(argv)
@@ -19,6 +57,14 @@ module Securial
 
     private
 
+    # Processes option flags from the command line arguments.
+    #
+    # Parses options like --version and --help, executing their actions
+    # if present and removing them from the argument list.
+    #
+    # @param argv [Array<String>] command line arguments
+    # @return [nil, Integer] nil to continue processing, or exit code
+    #
     def handle_flags(argv)
       parser = create_option_parser
 
@@ -32,6 +78,14 @@ module Securial
       end
     end
 
+    # Processes commands from the command line arguments.
+    #
+    # Identifies the command (e.g., 'new') and delegates to the appropriate
+    # handler method for that command.
+    #
+    # @param argv [Array<String>] command line arguments
+    # @return [Integer] exit status code (0 for success, non-zero for errors)
+    #
     def handle_commands(argv)
       cmd = argv.shift
 
@@ -44,6 +98,14 @@ module Securial
       end
     end
 
+    # Handles the 'new' command for creating Rails applications.
+    #
+    # Validates that an application name is provided, then delegates to
+    # securial_new to create the application with Securial.
+    #
+    # @param argv [Array<String>] remaining command line arguments
+    # @return [Integer] exit status code (0 for success, non-zero for errors)
+    #
     def handle_new_command(argv)
       app_name = argv.shift
 
@@ -57,6 +119,12 @@ module Securial
       0
     end
 
+    # Creates and configures the option parser.
+    #
+    # Sets up the command-line options and their handlers.
+    #
+    # @return [OptionParser] configured option parser instance
+    #
     def create_option_parser
       OptionParser.new do |opts|
         opts.banner = "Usage: securial [options] <command> [command options]\n\n"
@@ -79,6 +147,10 @@ module Securial
       end
     end
 
+    # Displays the current Securial version.
+    #
+    # @return [void]
+    #
     def show_version
       require "securial/version"
       puts "Securial v#{Securial::VERSION}"
@@ -86,6 +158,15 @@ module Securial
       puts "Securial version information not available."
     end
 
+    # Creates a new Rails application with Securial pre-installed.
+    #
+    # Orchestrates the process of creating a Rails application, adding the
+    # Securial gem, installing dependencies, and configuring the application.
+    #
+    # @param app_name [String] name of the Rails application to create
+    # @param rails_options [Array<String>] options to pass to 'rails new'
+    # @return [void]
+    #
     def securial_new(app_name, rails_options)
       puts "🏗️  Creating new Rails app: #{app_name}"
 
@@ -97,27 +178,53 @@ module Securial
       print_final_instructions(app_name)
     end
 
+    # Creates a new Rails application.
+    #
+    # @param app_name [String] name of the Rails application to create
+    # @param rails_options [Array<String>] options to pass to 'rails new'
+    # @return [Integer] command exit status
+    #
     def create_rails_app(app_name, rails_options)
       rails_command = ["rails", "new", app_name, *rails_options]
       run(rails_command)
     end
 
+    # Adds the Securial gem to the application's Gemfile.
+    #
+    # @param app_name [String] name of the Rails application
+    # @return [void]
+    #
     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
 
+    # Installs gems for the application using Bundler.
+    #
+    # @param app_name [String] name of the Rails application
+    # @return [Integer] command exit status
+    #
     def install_gems(app_name)
       run("bundle install", chdir: app_name)
     end
 
+    # Installs and configures Securial in the application.
+    #
+    # @param app_name [String] name of the Rails application
+    # @return [Integer] command exit status
+    #
     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
 
+    # Mounts the Securial engine in the application's routes.
+    #
+    # @param app_name [String] name of the Rails application
+    # @return [void]
+    #
     def mount_securial_engine(app_name)
       puts "🔗  Mounting Securial engine in routes"
       routes_path = File.join(app_name, "config/routes.rb")
@@ -128,6 +235,11 @@ module Securial
       File.write(routes_path, updated)
     end
 
+    # Prints final setup instructions after successful installation.
+    #
+    # @param app_name [String] name of the Rails application
+    # @return [void]
+    #
     def print_final_instructions(app_name)
       puts <<~INSTRUCTIONS
         🎉  Securial has been successfully installed in your Rails app!
@@ -140,6 +252,16 @@ module Securial
       INSTRUCTIONS
     end
 
+    # Runs a system command with optional directory change.
+    #
+    # Executes the provided command, optionally in a different directory,
+    # and handles success/failure conditions.
+    #
+    # @param command [String, Array<String>] command to run
+    # @param chdir [String, nil] directory to change to before running command
+    # @return [Integer] command exit status code (0 for success)
+    # @raise [SystemExit] if the command fails
+    #
     def run(command, chdir: nil)
       puts "→ #{command.inspect}"
       result =
@@ -156,3 +278,5 @@ module Securial
     end
   end
 end
+
+# rubocop:enable Rails/Exit, Rails/Output

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

data/lib/securial/error.rb

@@ -1,9 +1,39 @@
+# Requires all error classes used in the Securial framework.
+#
+# This file serves as the central error management system for Securial,
+# loading all specialized error types and establishing the Error namespace.
+# Each error type extends from BaseSecurialError and provides specific
+# error handling for different parts of the framework.
+#
+# @example Accessing a specific error type
+#   begin
+#     # Some operation that might fail
+#   rescue Securial::Error::Auth::TokenDecodeError => e
+#     # Handle token decoding errors
+#   rescue Securial::Error::Config::ValidationError => e
+#     # Handle configuration validation errors
+#   rescue Securial::Error::BaseError => e
+#     # Handle any other Securial errors
+#   end
+#
 require "securial/error/base_securial_error"
 require "securial/error/config"
 require "securial/error/auth"
 
 module Securial
-  module Error
-    # This serves as a namespace for all Securial errors.
-  end
+  # Namespace for all Securial-specific errors and exceptions.
+  #
+  # The Error module contains specialized error classes for different
+  # components of the Securial framework, organized into submodules
+  # for better categorization:
+  #
+  # - {BaseError} - Base class for all Securial errors
+  # - {Config} - Configuration-related errors
+  # - {Auth} - Authentication and authorization errors
+  #
+  # @see Securial::Error::BaseError
+  # @see Securial::Error::Config
+  # @see Securial::Error::Auth
+  #
+  module Error; end
 end